SuperX - Benutzerbeiträge [de]

Kernmodul Regelbetrieb

2026-08-04T07:55:26Z

Andrek:

=BI Maintenance=
[[image:logobutton_maintenance2b.png|200px]]

==Ziel und Überblick==
Die hier bereitgestellten Skripte ermöglichen es, in der BI-Umgebung von HISinOne und in Zukunft auch von SuperX (aktuell können die Scripte in SuperX leider noch nicht verwendet werden) Modul-Updates und -Upgrades zuverlässig über die Shell auszuführen – automatisiert per Cronjob oder manuell. Sie orientieren sich bewusst am bisherigen Vorgehen aus SuperX, wurden jedoch erweitert:

* Ausführung der BI-Modul-Updates/-Upgrades über Java (''ComponentAdminCLI'').
* Vollständige Protokollierung in Logdateien.
* Optional: Protokollierung der Läufe in der Tabelle <code>update_prot</code>.
* Automatischer Mailversand über ein konfigurierbares Mailprogramm.
* Optional: Erkennen interner Fehler im Batch-Job (auch wenn Java Exitcode 0 liefert).
* Möglichkeit, Logdateien automatisch an Mails anzuhängen (erfolgreiche und fehlerhafte Module).

==Installation aus dem git Repository==

Führen Sie folgenden Shell-Befehl aus:

git clone https://git.campussource.de/git/SuperX/BI_Maintenance.git

Die weitere Konfiguration wird im Folgenden beschrieben. Alle Einstellungen erfolgen zentral in der Datei <code>BI_ENV</code>, die als Template <code>BI_ENV.sam</code> ausgeliefert wird.

==Umgebungsvariablen in der BI_ENV==

===BI_ENV.sam – Template und lokale BI_ENV===
Die Datei <code>BI_ENV.sam</code> wird als Muster ausgeliefert.

Sie muss vor Ort:

# in <code>BI_ENV</code> kopiert/umbenannt werden:
<source lang="bash">
cp BI_ENV.sam BI_ENV
</source>
# an die lokalen Gegebenheiten angepasst werden (Pfade, Module, Mailadressen usw.).
# mit restriktiven Rechten versehen werden:
<source lang="bash">
chmod 600 BI_ENV
</source>

Skripte binden diese Datei später mit
<source lang="bash">
. /pfad/zu/BI_ENV
</source>
ein.

----

===Bedeutung der Variablen===
Im Folgenden die wichtigsten Variablen, die angepasst werden müssen.

====Java-Konfiguration====
<source lang="bash">
JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export JAVA_HOME

JRE_HOME=$JAVA_HOME
export JRE_HOME

PATH=$JAVA_HOME/bin:$PATH
export PATH
</source>

Diese Variablen stellen sicher, dass die BI-Jobs mit dem vorgesehenen Java (empfohlen: Java 17) ausgeführt werden.

Java-Optionen:
<source lang="bash">
JAVA_OPTS="-Xmx1520M -Djava.awt.headless=true ... --add-opens ..."
export JAVA_OPTS
</source>

====Pfade zur SuperX-BI-Installation====
<source lang="bash">
WEBAPP=/var/lib/tomcat10/webapps/superx
export WEBAPP

SUPERX_DIR=$WEBAPP/WEB-INF/conf/edustore
export SUPERX_DIR
</source>

Diese Pfade müssen an lokale Tomcat-Installation und SuperX-Verzeichnisstruktur angepasst werden.

====Modulsteuerung====
Für die Update- und Upgrade-Skripte werden die zu bearbeitenden Module festgelegt:

<source lang="bash">
export BI_UPDATE_MODULES="sos kenn zul"
export BI_UPGRADE_MODULES="kenn"
</source>

Hinweis:
Die Modulkürzel müssen klein geschrieben sein (z. B. <code>sos</code>, <code>kenn</code>, <code>zul</code>) und mit Leerzeichen getrennt aufgelistet werden.

====Logging====
<source lang="bash">
LOGPFAD=$WEBAPP/WEB-INF/logs
export LOGPFAD
</source>

Im Logpfad werden u. a. folgende Dateien erzeugt:
* <code>bi_update.log</code> – Sammellog des Updates
* <code>bi_upgrade.log</code> – Sammellog des Upgrades
* <code><modul>_update.log</code>
* <code><modul>_upgrade.log</code>

Java-Batch-Jobs erzeugen ergänzende Logs in:

<code>$WEBAPP/WEB-INF/logs/jobs</code>

====Mailversand====
Folgende Variablen steuern Empfänger und Format der Benachrichtigungen:

<source lang="bash">
export ERRORMAIL="admin@hs.de"
export LOGMAIL="$ERRORMAIL"
#export LOGMAIL="admin@hs.de kollege@hs.de" # mehrere Empfänger möglich
</source>

* <code>ERRORMAIL</code> – Empfänger für Fehlermails
* <code>LOGMAIL</code> – Empfänger für Erfolgs- und Statusmails
Mehrere Adressen werden per Leerzeichen getrennt.

Mailprogramm:
<source lang="bash">
export MAILPROG="s-nail --account=test1 -S ttycharset=utf-8 -S sendcharset=utf-8"
</source>

Betreffzeilen:
<source lang="bash">
export MAIL_BETREFF_UPDATE="BI Job Update"
export MAIL_BETREFF_UPGRADE="BI Job Upgrade"
export MAIL_BETREFF_SUFFIX_ERFOLGREICH=" - Erfolgreich"
export MAIL_BETREFF_SUFFIX_FEHLER=" - Fehler"
</source>
[[Datei:Kernmodul Regelbetrieb Mailversand.png|rand|links]]

So könnten die Mails aussehen.

====Steuerung der Log-Anhänge====
<source lang="bash">
# error = Logs nur bei Fehlern anhängen
# always = Logs immer anhängen (Erfolg + Fehler)
export MAIL_ATTACH_LOGS_MODE="error"
</source>

====Optionale Prüfung der Modul-Logs====
<source lang="bash">
# true = zusätzlich Modul-Log auf interne Fehler prüfen
# false = nur Exitcode des Java-Calls verwenden
export CHECK_JOBLOG_FOR_ERRORS="true"
</source>

Gerade bei dem Java Aufruf von ComponentAdminCLI empfehlenswert, da dieser aktuell noch trotz <code>status: FAILED</code> oft Exitcode 0 liefert.

----

=Module Updates=

==modules_update.sh – Hauptskript==
Dieses Skript führt alle Module aus <code>BI_UPDATE_MODULES</code> nacheinander aus.

Ablauf:

# Startcheck: Sind <code>WEBAPP</code>, <code>LOGPFAD</code> und <code>BI_UPDATE_MODULES</code> gesetzt?
# Falls verfügbar: DB-Protokollierung via <code>DOQUERY</code>.
# Für jedes Modul:
## Logdatei anlegen
## Start in <code>update_prot</code> protokollieren (update_id = -10000)
## Java-Update starten:
<code>ComponentAdminCLI -e <modul></code>
## Optional: Modul-Logdatei nach internen Fehlern durchsuchen
## Erfolg:
### Modul-Log in <code>SUCCESS_LOG_FILES</code>
### DB-Update (update_id = -10000)
## Fehler:
### Modul-Log in <code>ERROR_LOG_FILES</code>
### DB-Update (update_id = -10001)
## Zuletzt: Java-Joblogs aus <code>$WEBAPP/WEB-INF/logs/jobs</code> ermitteln

# Nach Abschluss aller Module:
## Erfolgs- oder Fehlermail versenden
## Anhänge abhängig von <code>MAIL_ATTACH_LOGS_MODE</code>

==modules_update_cron.sh – Wrapper für Cron==
Damit Updates regelmäßig durchgeführt werden können, existiert ein einfaches Wrapper-Skript.

Vorgehen:

# Beispieldatei kopieren:
<source lang="bash">
cp modules_update_cron.sh.sam modules_update_cron.sh
chmod +x modules_update_cron.sh
</source>
# Pfade zur <code>BI_ENV</code> und zum Update-Skript anpassen.
# Cronjob eintragen, z. B. werktags um 18 Uhr:
<source lang="bash">
0 18 * * 1-5 /pfad/zu/modules_update_cron.sh
</source>

Inhaltlich:
* Laden der <code>BI_ENV</code>
* Start des Skripts <code>modules_update.sh</code>

----

=Module Upgrades=

==modules_upgrade.sh – Hauptskript==
Das Upgrade-Skript entspricht dem Update-Skript, unterscheidet sich aber in folgenden Punkten:

* Es wird **manuell** ausgeführt – kein Cronjob vorgesehen.
* Es verwendet <code>BI_UPGRADE_MODULES</code>.
* Das eigentliche Upgrade erfolgt über:
<code>ComponentAdminCLI -u <modul></code>
* Nach Abschluss des Upgrades erfolgt ein Mailversand analog zum Update-Skript.

Aufruf:

<source lang="bash">
cd /var/lib/tomcat10/webapps/superx/WEB-INF/bin/BI-Maintenance/update
./modules_upgrade.sh
</source>

Vorher muss zu Beginn des Skripts der Pfad zur <code>BI_ENV</code> eingetragen sein:

<source lang="bash">
. /pfad/zur/BI_ENV
</source>

----

=Modulverwaltung=

==Modulkürzel==
Die folgenden Modulkürzel sind in einer typischen BI-Installation relevant:

<source lang="sql">
kuerzel | name
---------+-------------------------------------------------------
astat | Amtliche Statistik
bau | Gebäude, Räume, Flächen
cob | Kostenrechnung
erfolg | Studienverlauf
fin | Finanzrechnung
gang | Studiengänge
ivs | Inventar
kenn | Kennzahlen
kern | Administration
lm | Leistungsmonitoring
man | Management
prom | Promovierende
res | Forschung
sos | Studierende, Prüfungen
sva | Personal, Stellen
zul | Bewerbung, Zulassung
</source>

Die aktiven Module der eigenen Installation können mit folgendem SQL abgefragt werden:

<source lang="sql">
SELECT V.his_system AS kuerzel,
S.name
FROM db_version V
JOIN systeminfo S
ON S.tid = V.systeminfo_id
ORDER BY 1;
</source>

=Migration auf die Webapp-Struktur=

Das bereitgestellte Migrationsskript ermöglicht die Umstellung einer bestehenden SuperX-Installation auf die empfohlene Webapp-Struktur.

Dabei können sowohl klassische Installationen mit separatem DB-Verzeichnis als auch bestehende Webapp-Installationen migriert werden. Die Migration kann je nach Anwendungsfall vollständig oder ausschließlich für das DB-Verzeichnis durchgeführt werden.
Hier eine Anleitung "in short", wenn Sie bisher das "klasssische" Layout genutzt haben (also Unix Benutzer "superx", Installation in "/home/superx").

git clone https://git.campussource.de/git/SuperX/BI_Maintenance.git
#Script ausführen und neues ENV laden:
cd BI_Maintenance/webapps_migration
./migrate_superx_webapp.sh

Das Skript liest die bestehende Installation anhand der vorhandenen SQL_ENV-Datei ein und erzeugt daraus die gewünschte Zielstruktur. Details können in der Konfigurationsdatei
<source lang="text">
migrate_superx.conf
</source>
konfiguriert, siehe folgende Dokumentation.

==Zielstruktur==

Die Webapp wird standardmäßig nicht direkt im Tomcat-Webapp-Verzeichnis abgelegt, sondern unter:

<source lang="text">
/home/superx/webapps/superx
</source>

Dadurch bleibt die Installation unabhängig von der verwendeten Tomcat-Distribution und kann einfacher per Git, rsync oder Modulupdate gepflegt werden.

Die zugehörige DB-Struktur befindet sich anschließend unter:

<source lang="text">
/home/superx/webapps/superx/WEB-INF/conf/edustore/db
</source>

==Tomcat-Anbindung==

Für den Zugriff des Tomcat-Servers auf die Webapp gibt es grundsätzlich zwei Möglichkeiten:

* Verwendung eines symbolischen Links vom Tomcat-Webapp-Verzeichnis auf die eigentliche Webapp.
* Anpassung der Tomcat-Konfiguration (z. B. appBase oder Context-Konfiguration).

Empfohlen wird die Verwendung eines symbolischen Links.

Beispiel:

<source lang="text">
/srv/tomcat/webapps/superx
-> /home/superx/webapps/superx
</source>

==Wichtige Variablen==

Die wichtigsten Einstellungen erfolgen in der Datei:

<source lang="text">
migrate_superx.conf
</source>

===TARGET_WEBAPP===

Definiert das Zielverzeichnis der Webapp.

Beispiel:

<source lang="bash">
TARGET_WEBAPP="/home/superx/webapps/superx"
</source>

===WEBAPP_USER===

Definiert den Besitzer der Ziel-Webapp.

Beispiel:

<source lang="bash">
WEBAPP_USER="superx"
</source>

===WEBAPP_GROUP===

Definiert die Gruppe der Ziel-Webapp.

Beispiel:

<source lang="bash">
WEBAPP_GROUP="tomcat"
</source>

Ergebnis:

<source lang="text">
Owner: superx
Group: tomcat
</source>

===MIGRATION_MODE===

Steuert die Art der Migration.

Vollständige Migration:

<source lang="bash">
MIGRATION_MODE="full"
</source>

Nur Migration des DB-Verzeichnisses:

<source lang="bash">
MIGRATION_MODE="db_only"
</source>

==Migration des DB-Verzeichnisses==

Das DB-Verzeichnis kann entweder kopiert oder verschoben werden.

===DB_TRANSFER_MODE=copy===

Das bestehende DB-Verzeichnis bleibt erhalten.

<source lang="bash">
DB_TRANSFER_MODE="copy"
</source>

Intern wird hierfür rsync verwendet.

===DB_TRANSFER_MODE=move===

Das DB-Verzeichnis wird verschoben.

<source lang="bash">
DB_TRANSFER_MODE="move"
</source>

Intern wird hierfür mv verwendet. Ist das Zielverzeichnis bereits vorhanden und
<code>ALLOW_EXISTING_TARGET_DB="true"</code> gesetzt, wird das vorhandene Ziel-DB-Verzeichnis vor dem Verschieben vollständig ersetzt. Damit verbleiben keine alten Dateien im Ziel.

Dies ist der empfohlene Standard für die Migration klassischer SuperX-Installationen und vermeidet unnötigen zusätzlichen Speicherbedarf.

==Automatische Anpassung der SQL_ENV==

Nach der Migration kann die SQL_ENV-Datei automatisch angepasst werden.

Dabei werden insbesondere folgende Variablen aktualisiert:

<source lang="bash">
SUPERX_DIR
WEBAPP
</source>

Zusätzlich wird sichergestellt, dass folgende Einstellung vorhanden ist:

<source lang="bash">
umask 002
</source>

Vor der Änderung wird automatisch eine Sicherungskopie der SQL_ENV-Datei angelegt.

==Benutzer und Gruppen==

Die folgenden Variablen steuern, welchem Benutzer und welcher Gruppe die Ziel-Webapp nach der Migration zugeordnet wird.

===WEBAPP_USER===

Definiert den Besitzer der Ziel-Webapp.

Beispiel:

<source lang="bash">
WEBAPP_USER="superx"
</source>

Alle Dateien und Verzeichnisse der Ziel-Webapp werden diesem Benutzer zugeordnet, sofern die Rechteverwaltung aktiviert ist.

===WEBAPP_GROUP===

Definiert die Gruppe der Ziel-Webapp.

Beispiel:

<source lang="bash">
WEBAPP_GROUP="tomcat"
</source>

Die Gruppe wird für alle Dateien und Verzeichnisse der Ziel-Webapp verwendet.

Durch das gesetzte setgid-Bit auf den Verzeichnissen erben neu angelegte Dateien und Unterverzeichnisse automatisch diese Gruppe.

==Automatische Rechtebehandlung==

Die Migration kann sowohl als root als auch – unter bestimmten Voraussetzungen – direkt als Anwendungsbenutzer ausgeführt werden.

===SET_OWNER=auto===

Dies ist die empfohlene Standardeinstellung.

<source lang="bash">
SET_OWNER="auto"
</source>

Das Skript entscheidet abhängig vom aktuellen Benutzer automatisch, ob ein Besitzerwechsel erforderlich ist.

====Ausführung als root====

Wird das Skript als root ausgeführt, werden Besitzer und Gruppe der Ziel-Webapp auf die konfigurierten Werte gesetzt.

<source lang="bash">
chown -R $WEBAPP_USER:$WEBAPP_GROUP ...
</source>

Zusätzlich wird auch das übergeordnete Verzeichnis der Webapp (z. B. /home/superx/webapps) auf die gleichen Besitz- und Gruppenrechte gesetzt.

====Ausführung als WEBAPP_USER====

Wird das Skript direkt als der konfigurierte WEBAPP_USER ausgeführt und ist dieser Benutzer Mitglied der konfigurierten WEBAPP_GROUP, wird kein chown ausgeführt.

Stattdessen verwendet das Skript bei Bedarf ein chgrp, um die Gruppenzugehörigkeit der Dateien anzupassen.

In diesem Fall kann die Migration häufig vollständig ohne root-Rechte durchgeführt werden.

====Ausführung als anderer Benutzer====

Wird das Skript weder als root noch als WEBAPP_USER mit passender Gruppenmitgliedschaft ausgeführt, bricht das Skript mit einer entsprechenden Fehlermeldung ab.

===ADD_WEBAPP_USER_TO_GROUP===

Optional kann das Skript die Gruppenmitgliedschaft des Zielbenutzers automatisch anpassen.

<source lang="bash">
ADD_WEBAPP_USER_TO_GROUP="true"
</source>

Hierfür sind root-Rechte erforderlich.

==Tomcat-Symlink==

Optional kann das Skript den Symlink für den Tomcat automatisch erzeugen.

===CREATE_TOMCAT_SYMLINK===

<source lang="bash">
CREATE_TOMCAT_SYMLINK="true"
</source>

===TOMCAT_WEBAPPS_DIR===

<source lang="bash">
TOMCAT_WEBAPPS_DIR="/srv/tomcat/webapps"
</source>

===TOMCAT_CONTEXT_NAME===

<source lang="bash">
TOMCAT_CONTEXT_NAME="superx"
</source>

===REPLACE_EXISTING_SYMLINK===

Bestehende Symlinks können bei Bedarf automatisch ersetzt werden.

<source lang="bash">
REPLACE_EXISTING_SYMLINK="true"
</source>

Normale Dateien oder Verzeichnisse werden dabei niemals automatisch gelöscht.

==Sicherheitsprüfungen==

Vor Beginn der Migration werden verschiedene Sicherheitsprüfungen durchgeführt.

Unter anderem wird geprüft:

* Existiert die SQL_ENV-Datei?
* Existiert der konfigurierte Benutzer?
* Existiert die konfigurierte Gruppe?
* Sind Quell- und Zielverzeichnis identisch?
* Würde eine Verzeichnisverschachtelung entstehen?
* Befindet sich SUPERX_DIR bereits innerhalb von WEBAPP?

Wird erkannt, dass die Installation bereits der neuen Struktur entspricht, bricht das Skript standardmäßig ab.

===FORCE_ALREADY_MIGRATED===

In Ausnahmefällen kann diese Prüfung übersteuert werden.

<source lang="bash">
FORCE_ALREADY_MIGRATED="true"
</source>

Dies sollte nur verwendet werden, wenn die Auswirkungen bekannt sind.

==Typischer Ablauf==

# Laden der migrate_superx.conf
# Laden der bestehenden SQL_ENV
# Ermitteln von SUPERX_DIR, WEBAPP und DB-Verzeichnis
# Sicherheitsprüfungen
# Optionales Stoppen des Tomcat-Dienstes
# Kopieren der Webapp
# Kopieren oder Verschieben des DB-Verzeichnisses
# Anpassen der SQL_ENV
# Setzen von Besitzern, Gruppen und Rechten
# Optionales Erzeugen des Tomcat-Symlinks
# Optionales Starten des Tomcat-Dienstes

==Empfohlene Standardkonfiguration==

<source lang="bash">
TARGET_WEBAPP="/home/superx/webapps/superx"

WEBAPP_USER="superx"
WEBAPP_GROUP="tomcat"

MIGRATION_MODE="db_only"
DB_TRANSFER_MODE="move"

SET_OWNER="auto"
SET_RIGHTS="true"
SET_CHMOD="true"

CREATE_TOMCAT_SYMLINK="true"
</source>

==Hinweise==

* Standardziel ist /home/superx/webapps/superx.
* Die Tomcat-Anbindung kann über einen Symlink erfolgen.
* Bei WEBAPP_USER=superx und WEBAPP_GROUP=tomcat kann die Migration häufig ohne root erfolgen, sofern der Benutzer Mitglied der Gruppe tomcat ist.
* Root wird nur benötigt, wenn Besitzer geändert, Benutzer oder Gruppen angepasst oder Systemkonfigurationen verändert werden müssen.

Kernmodul Komponentenverwaltung

2026-07-14T12:29:28Z

Andrek:

Die Komponentenverwaltung im Kernmodul kann je nach Aufgabe über die Browseroberfläche oder über Shell-Skripte erfolgen.

Bisher wurden Installation, Deinstallation, Aktualisierung und Upgrade von Modulen überwiegend über Skripte in der Shell durchgeführt. Ab Kernmodul 6.0 steht zusätzlich eine Komponentenverwaltung über die Browseroberfläche zur Verfügung. Diese Browseroberfläche wird im Folgenden als SuperX Komponentenverwaltung beschrieben.

Die SuperX Komponentenverwaltung ist vor allem für die Ausführung und Überwachung von ETL-Prozessen, für Modul-Upgrades sowie für die Installation von im Dateisystem vorhandenen Modulen vorgesehen. Die Deinstallation von Modulen erfolgt weiterhin über die Shell-Skripte.

Der folgende Artikel ist daher in zwei Bereiche gegliedert: Zuerst wird die Nutzung der SuperX Komponentenverwaltung beschrieben. Anschließend folgt die Dokumentation zur Installation und Verwaltung von Modulen mit Skripten.

= Komponentenverwaltung im Browser: SuperX Komponentenverwaltung =
Die SuperX Komponentenverwaltung dient dazu, ETL-Prozesse der SuperX-Module über die Weboberfläche auszuführen und zu überwachen. Sie bietet eine zentrale Übersicht über installierte und installierbare Module, verfügbare Aktionen, Versionsinformationen, Datenquellen, den aktuellen Lauf sowie technische Zusatzinformationen für die Fehlersuche.

Der Schwerpunkt der Oberfläche liegt auf dem täglichen Betrieb: Anwenderinnen und Anwender können Laderoutinen starten, den aktuellen Stand eines Laufs verfolgen und bei Bedarf die Log-Ausgabe einsehen. Technische Detail- und Diagnoseinformationen stehen ebenfalls zur Verfügung, sind aber vor allem für Administratorinnen und Administratoren oder den Support gedacht.

[[Bild:SuperX_ETL_Manager_Uebersicht.png|Gesamtübersicht der SuperX Komponentenverwaltung mit Modulübersicht, Filterbereich, Aktionsbuttons und aktuellem Lauf.]]

== Aufbau der Oberfläche ==

Die Oberfläche besteht im Wesentlichen aus folgenden Bereichen:

* Filterbereich
* Modulübersicht
* Aktionsbuttons pro Modul
* Bereich „Aktueller Lauf“
* Log-Ausgabe
* Details-Bereich
* Diagnose-Bereich

Über den Filterbereich kann die angezeigte Modulliste eingeschränkt werden. Die Modulübersicht zeigt die wichtigsten Informationen zu den vorhandenen Modulen. Über die Aktionsbuttons können ETL-Prozesse gestartet werden. Der Bereich „Aktueller Lauf“ zeigt den zuletzt gestarteten oder aktuell laufenden Prozess an.

Die Bereiche „Details“ und „Diagnose“ liefern zusätzliche technische Informationen. Sie sind hilfreich für Supportfälle, aber für die normale Bedienung nicht zwingend erforderlich.

== Modulübersicht ==

Die Modulübersicht zeigt die installierten sowie die im Dateisystem erkannten installierbaren Module mit ihren wichtigsten Eigenschaften.

{| class="wikitable"
! Spalte
! Bedeutung
|-
| Modul
| Zeigt den Namen und das technische Kürzel des Moduls, zum Beispiel „Administration“ mit dem Kürzel „kern“ oder „Kennzahlen“ mit dem Kürzel „kenn“.
|-
| Status
| Zeigt, ob das Modul installiert ist. Nicht installierte, aber im Dateisystem verfügbare Module können ebenfalls erscheinen.
|-
| Versionen
| Zeigt die installierte Version und die verfügbare Version des Moduls.
|-
| Letztes Update
| Zeigt den Zeitpunkt des letzten bekannten Updates.
|-
| Datenquelle
| Zeigt, aus welcher Datenquelle das Modul seine Daten bezieht oder auf welcher Datenbasis der ETL-Prozess arbeitet.
|-
| DB-Verbindung
| Zeigt, ob die Verbindung zur Datenbank bzw. Datenquelle aktuell erreichbar ist.
|-
| Aktionen
| Zeigt die verfügbaren Aktionen für das jeweilige Modul. Bei nicht installierten Modulen wird anstelle von „Upgrade“ die Aktion „Installieren“ angeboten.
|}

=== Versionen ===

In der Spalte „Versionen“ werden zwei Werte angezeigt:

* installierte Version
* verfügbare Version

Die installierte Version beschreibt den Stand, der aktuell in der Datenbank installiert ist. Die verfügbare Version beschreibt den ausgelieferten Stand des Moduls, der in der Installation vorliegt.

Wenn die verfügbare Version höher ist als die installierte Version, sollte in der Regel ein Upgrade des Moduls durchgeführt werden. Dadurch werden die Datenstrukturen des Moduls auf den ausgelieferten Stand aktualisiert.

=== Datenquelle ===

Die Datenquelle gibt an, aus welchem System ein Modul seine Daten bezieht oder auf welcher Datenbasis es arbeitet.

SuperX ist ein Data Warehouse. Viele Module übernehmen Daten aus externen vorsystemen. Beispiele für solche Datenquellen sind:

* cob für Kostenrechnung
* mbs für Finanzrechnung, Inventar oder Gebäude/Räume/Flächen
* sva für Personal- und Stelleninformationen
* hisinone bei entsprechend angebundenen Modulen

Daneben gibt es Module, die auf bereits in SuperX vorhandene Daten zurückgreifen. In solchen Fällen wird als Datenquelle „SuperX“ angezeigt. Das betrifft vor allem Module, die modulübergreifend, auswertungsorientiert oder spezialisiert auf vorhandene SuperX-Daten zugreifen.

Beispiele hierfür können sein:

* kenn für Kennzahlen
* man für Managementberichte
* erfolg für Studienverlauf bzw. Erfolgsbetrachtungen
* gang für Studiengänge

Die Datenquelle „SuperX“ bedeutet also nicht, dass keine Daten verarbeitet werden. Sie zeigt an, dass die Verarbeitung auf Daten basiert, die bereits im SuperX-System vorhanden sind.

== Aktionen ausführen ==

Die verfügbaren Aktionen hängen vom jeweiligen Modul ab. Nicht jedes Modul unterstützt alle Aktionen. Wenn eine Aktion nicht verfügbar ist, wird der entsprechende Button nicht angezeigt oder ist nicht aktiv.

Die Oberfläche ermittelt die ausführbaren Aktionen aus den verfügbaren technischen Jobs des jeweiligen Moduls. Falls die Jobliste nicht vollständig geliefert wird, können die grundsätzlichen Angaben aus der Komponentenliste als Fallback genutzt werden. Dadurch können Standardaktionen wie „Unload“, „Update“ oder „Unload & Update“ trotzdem angeboten werden, wenn sie für das Modul grundsätzlich vorgesehen sind.

Vor dem Start einer Aktion erscheint ein Bestätigungsdialog. Dort werden die geplante Aktion, der Modulname und das technische Kürzel angezeigt. Technische REST-Aufrufe werden im normalen Dialog nicht angezeigt.

[[Bild:SuperX_ETL_Manager_Aktionsbuttons.png|Modulzeile mit den Aktionsbuttons Unload, Update, Unload & Update sowie Installieren bzw. Upgrade.]]

=== Unload ===

Die Aktion „Unload“ entlädt Daten aus einem angebundenen Vorsystem, sofern für das Modul ein Vorsystem angebunden ist.

Der Unload dient dazu, Daten aus der jeweiligen Datenquelle bereitzustellen, damit sie anschließend in SuperX verarbeitet werden können. Je nach Modul und Einrichtung kann der Unload auch dazu dienen, Daten für eine weitere Verarbeitung oder Übertragung bereitzustellen.

=== Update ===

Die Aktion „Update“ lädt vorhandene Rohdaten in SuperX ein und führt die Hauptladeroutine des Moduls aus.

Dies ist in vielen Fällen die wichtigste Aktion für den täglichen Betrieb. Beim Update werden die vorhandenen Rohdaten verarbeitet und die zugehörigen SuperX-Tabellen aktualisiert.

=== Unload & Update ===

Die Aktion „Unload & Update“ führt zuerst den Unload und anschließend das Update aus.

Diese Aktion ist sinnvoll, wenn neue Daten aus einem angebundenen Vorsystem entladen und direkt anschließend in SuperX verarbeitet werden sollen.

=== Installieren ===

Die Aktion „Installieren“ wird angezeigt, wenn ein Modul im Dateisystem vorhanden, aber noch nicht installiert ist.

Die Installation legt die benötigten Datenbankobjekte, Abfragen und weiteren Modulbestandteile an. Nach erfolgreicher Installation erscheint das Modul als installiert. An derselben Stelle wird dann statt „Installieren“ die Aktion „Upgrade“ angezeigt.

=== Upgrade ===

Die Aktion „Upgrade“ führt eine Modulaktualisierung durch. Dabei werden die Datenstrukturen des Moduls auf den ausgelieferten Stand gebracht.

Ein Upgrade sollte ausgeführt werden, wenn eine neue verfügbare Version angezeigt wird oder wenn dies im Rahmen eines Modulupdates erforderlich ist.

== Sonderfall Kennzahlen-Modul ==

Beim Kennzahlen-Modul „kenn“ ist die Verarbeitung etwas anders als bei typischen Modulen mit externem Vorsystem.

Die Datenquelle ist hier in der Regel „SuperX“. Das bedeutet, dass die Kennzahlen nicht primär aus einem externen Fremdsystem entladen werden. Stattdessen basiert die Verarbeitung auf Daten, die bereits in SuperX vorhanden sind.

Für den täglichen Betrieb ist beim Kennzahlen-Modul daher häufig vor allem die Aktion „Update“ relevant. Dabei werden die Kennzahlen auf Basis der vorhandenen SuperX-Daten neu berechnet bzw. aktualisiert.

Je nach Einrichtung können beim Kennzahlen-Modul auch „Unload“ oder „Unload & Update“ angeboten werden. Die Oberfläche richtet sich dabei nach den verfügbaren Jobs bzw. nach den Modulangaben aus der Komponentenliste.

Die Aktion „Unload“ kann beim Kennzahlen-Modul eine andere Bedeutung haben als bei klassischen Vorsystem-Modulen. Sie kann dazu dienen, Kennzahlen für ein anderes System bereitzustellen, zum Beispiel:

* für ein hochschulübergreifendes SuperX
* für Vergleichssysteme
* für landesweite Auswertungen oder Berichtssysteme

Die kombinierte Aktion „Unload & Update“ ist beim Kennzahlen-Modul daher nicht immer die wichtigste Aktion. In vielen Installationen wird das Update gezielt über die Oberfläche ausgeführt, während Export- oder Übertragungsprozesse über automatische Abläufe wie Cronjobs gesteuert werden können.

== Aktueller Lauf ==

Der Bereich „Aktueller Lauf“ zeigt Informationen zum zuletzt gestarteten oder aktuell laufenden ETL-Prozess.

Typische Informationen sind:

* JobExecutionId
* Name des gestarteten Jobs
* Status
* Fortschritt
* Anzahl der ausgeführten Schritte
* Log-Ausgabe

[[Bild:SuperX_ETL_Manager_Aktueller_Lauf.png|Bereich „Aktueller Lauf“ mit JobExecutionId, Status, Fortschritt und Log-Ausgabe.]]

=== Status ===

Der Status zeigt den aktuellen Zustand des Laufs. Häufige Statuswerte sind:

{| class="wikitable"
! Status
! Bedeutung
|-
| STARTING
| Der Lauf wird gestartet.
|-
| STARTED
| Der Lauf wurde gestartet und wird ausgeführt.
|-
| COMPLETED
| Der Lauf wurde erfolgreich abgeschlossen.
|-
| FAILED
| Der Lauf ist mit einem Fehler abgebrochen.
|-
| STOPPED
| Der Lauf wurde gestoppt.
|}

=== Fortschritt ===

Der Fortschritt zeigt, wie viele Prozessschritte bereits abgearbeitet wurden. Er ist als technischer bzw. prozessbezogener Fortschritt zu verstehen.

Wichtig ist: Der Fortschrittswert ist keine genaue Zeitprognose.

Ein Lauf kann schnell auf eine hohe Prozentzahl springen und dort längere Zeit stehen bleiben, wenn ein einzelner Verarbeitungsschritt besonders lange dauert. Umgekehrt können viele kleine Schritte sehr schnell nacheinander abgeschlossen werden. Die Prozentanzeige beschreibt daher den Abarbeitungsstand der Prozessschritte, nicht die tatsächlich vergangene oder verbleibende Zeit.

Beispiel:

Ein Lauf kann bereits 80 % anzeigen, obwohl noch ein größerer Verarbeitungsschritt aussteht. Ebenso kann ein Lauf am Anfang längere Zeit bei einer niedrigen Prozentzahl stehen bleiben, wenn ein früher Prozessschritt besonders umfangreich ist.

== Log-Ausgabe ==

Die Log-Ausgabe zeigt technische Informationen zum ausgeführten ETL-Prozess. Sie kann helfen, den Ablauf nachzuvollziehen und bei Problemen erste Hinweise zu erhalten.

Die Log-Ausgabe ist vor allem für Supportfälle hilfreich. Für eine tiefergehende Fehleranalyse sind in der Regel administrative Kenntnisse erforderlich. Je nach Fehler müssen zusätzlich Serverlogs, Datenbankinhalte, Moduldateien oder Systemkonfigurationen geprüft werden.

Wenn die Log-Ausgabe nicht sofort erscheint, kann sie über „Log laden“ erneut abgefragt werden. Gerade bei umfangreichen Läufen kann es vorkommen, dass die Log-Ausgabe erst kurze Zeit nach Abschluss vollständig verfügbar ist.

== Typische Nutzungsszenarien ==

=== Bereits vorhandene Rohdaten verarbeiten ===

Wenn die Rohdaten bereits vorhanden sind und lediglich erneut verarbeitet werden sollen, wird in der Regel die Aktion „Update“ verwendet.

Beispiel:

* Rohdaten liegen bereits im System vor
* Berechnungen oder Aggregationen sollen neu ausgeführt werden
* die SuperX-Tabellen des Moduls sollen aktualisiert werden

Geeignete Aktion:

<pre>
Update
</pre>

=== Neue Daten aus einem Vorsystem übernehmen und verarbeiten ===

Wenn neue Daten aus einem externen Vorsystem übernommen und anschließend verarbeitet werden sollen, kann die Aktion „Unload & Update“ verwendet werden.

Dabei werden zunächst die Daten aus dem Vorsystem entladen. Anschließend werden die Daten durch das Update in SuperX verarbeitet.

Geeignete Aktion:

<pre>
Unload & Update
</pre>

=== Nur Daten aus einem Vorsystem entladen ===

Wenn Daten aus einem Vorsystem entladen werden sollen, ohne direkt anschließend die Laderoutine auszuführen, kann die Aktion „Unload“ verwendet werden.

Geeignete Aktion:

<pre>
Unload
</pre>

=== Modul installieren ===

Wenn ein Modul im Dateisystem vorhanden, aber noch nicht installiert ist, wird in der Modulzeile die Aktion „Installieren“ angezeigt.

Geeignete Aktion:

<pre>
Installieren
</pre>

=== Modul auf den ausgelieferten Stand aktualisieren ===

Wenn eine neue verfügbare Version angezeigt wird, sollte ein Upgrade geprüft bzw. durchgeführt werden.

Geeignete Aktion:

<pre>
Upgrade
</pre>

=== Kennzahlen innerhalb von SuperX aktualisieren ===

Beim Kennzahlen-Modul „kenn“ werden die Daten in der Regel aus SuperX selbst bezogen. Wenn die Kennzahlen neu berechnet oder aktualisiert werden sollen, ist häufig die Aktion „Update“ die passende Aktion.

Geeignete Aktion:

<pre>
Update
</pre>

=== Kennzahlen für ein anderes System bereitstellen ===

Wenn Kennzahlen für ein anderes System bereitgestellt werden sollen, kann beim Kennzahlen-Modul die Aktion „Unload“ relevant sein.

Dies kann zum Beispiel für hochschulübergreifende Auswertungen, Vergleichssysteme oder landesweite Berichtssysteme genutzt werden.

Geeignete Aktion:

<pre>
Unload
</pre>

== Hinweise zur Nutzung ==

Bei der Nutzung der SuperX Komponentenverwaltung sollten folgende Punkte beachtet werden:

* Ein laufender Prozess sollte nicht unnötig mehrfach parallel gestartet werden.
* Vor dem Start von Installieren, Upgrade, Unload, Update oder Unload & Update sollte der Bestätigungsdialog geprüft werden.
* Nach einem Lauf kann die Modulübersicht über „Aktualisieren“ neu geladen werden.
* Die Prozentanzeige ist kein Zeitindikator, sondern beschreibt den Fortschritt der Prozessschritte.
* Bei Fehlern sollte zuerst der Status und anschließend die Log-Ausgabe geprüft werden.
* Für tiefergehende Fehleranalysen sollten Administratorinnen und Administratoren oder technische Ansprechpartner einbezogen werden.
* Bei neuen verfügbaren Modulversionen sollte geprüft werden, ob ein Upgrade auszuführen ist.

== Details-Bereich ==

Über den Button „Details“ können zusätzliche technische Informationen zu einem Modul angezeigt werden.

Der Details-Bereich ist vor allem für fortgeschrittene Benutzerinnen und Benutzer, Administratorinnen und Administratoren oder den Support gedacht. Er kann unter anderem folgende Informationen enthalten:

* technische Modulkennung
* Systeminfo-ID
* technische Jobnamen
* verfügbare Jobs
* hergeleitete Startaktionen
* Rohdaten der Schnittstelle
* zusätzliche technische Moduldetails

Für den normalen Betrieb ist der Details-Bereich meist nicht erforderlich. Er ist vor allem dann hilfreich, wenn bei Rückfragen oder Supportfällen genaue technische Informationen benötigt werden.

== Diagnose-Bereich ==

Der Diagnose-Bereich ist eine technische Hilfsfunktion zur Prüfung der SuperX Komponentenverwaltung. Er ist global angeordnet und nicht auf ein einzelnes Modul beschränkt.

Die Diagnose führt keine Reparaturen automatisch aus. Sie zeigt technische Informationen, mögliche Auffälligkeiten und Hinweise an. Zusätzlich können SQL- oder Shell-Hinweise angezeigt werden, die bei Bedarf von Administratorinnen und Administratoren kopiert und manuell ausgeführt werden können.

Der Diagnose-Bereich kann unter anderem folgende Informationen enthalten:

* Erreichbarkeit der REST-Schnittstellen
* Webapp-, Tomcat- und Java-Informationen
* Pfade und Dateisysteminformationen
* Festplattenspeicher
* Datenbankinformationen
* Prüfung der Log-Tabelle
* Versionsquellen
* bekannte Fehlerbilder
* kopierbare SQL- und Shell-Hinweise

Der Diagnose-Bereich ist vor allem für Administratorinnen und Administratoren oder technische Ansprechpartner gedacht. Für normale Anwenderinnen und Anwender ist er in der Regel nur dann relevant, wenn ein Fehler auftritt oder technische Informationen weitergegeben werden sollen.

== Administratorhinweise ==

Dieser Abschnitt enthält ergänzende technische Hinweise. Er richtet sich vor allem an Administratorinnen und Administratoren sowie an den technischen Support.

=== Herkunft der Versionsinformationen ===

Die Oberfläche zeigt eine installierte und eine verfügbare Version an.

Die installierte Version beschreibt den Stand, der in der Datenbank installiert ist. Falls die REST-Schnittstelle keinen Wert liefert, kann die Version aus der Tabelle <code>db_version</code> gelesen werden.

Die verfügbare Version beschreibt den ausgelieferten Stand im Dateisystem. Sie kann aus der Modul-XML-Datei gelesen werden. Für normale Module liegt diese Datei typischerweise unter:

<pre>
WEB-INF/conf/edustore/db/module/<modul>/conf/<modul>.xml
</pre>

Für das Kernmodul gilt ein Sonderfall. Die Modul-XML liegt unter:

<pre>
WEB-INF/conf/edustore/db/install/conf/kern.xml
</pre>

Zusätzlich kann eine Datei <code>VERSION</code> im jeweiligen Modulverzeichnis als Fallback verwendet werden.

=== Log-Tabelle ===

Die Log-Ausgabe der SuperX Komponentenverwaltung verwendet eine Datenbanktabelle für die Joblogs. Wenn diese Tabelle fehlt oder unvollständig ist, kann die Log-Ausgabe fehlschlagen.

Eine mögliche Struktur der Tabelle ist:

<pre>
CREATE TABLE IF NOT EXISTS job_log
(
job_instance_id bigint NOT NULL,
log text,
status text
);

CREATE UNIQUE INDEX IF NOT EXISTS ix_job_log1
ON public.job_log USING btree (job_instance_id);
</pre>

Diese SQL-Anweisungen sollten nicht automatisch durch die Oberfläche ausgeführt werden. Sie dienen als Hinweis für Administratorinnen und Administratoren und müssen bei Bedarf manuell geprüft und ausgeführt werden.

=== Typische technische Fehlerbilder ===

{| class="wikitable"
! Fehlerbild
! Mögliche Ursache
|-
| <code>/jobLog/{id}</code> liefert HTTP 500
| Die Tabelle <code>job_log</code> fehlt, ist unvollständig oder der Logeintrag ist noch nicht verfügbar.
|-
| <code>/job/list/{modul}</code> liefert HTTP 500
| Moduldateien fehlen, Pfade stimmen nicht oder die Webapp verwendet nicht den erwarteten Dateistand.
|-
| REST-Endpunkt liefert HTTP 404
| Der Context-Pfad, die Webapp, der Port oder ein Tunnel zeigt möglicherweise nicht auf die erwartete Anwendung.
|-
| Log erscheint erst nach erneutem Laden
| Der ETL-Lauf ist abgeschlossen, aber der Logeintrag war beim ersten Abruf noch nicht vollständig verfügbar.
|}

== Zusammenfassung ==

Die SuperX Komponentenverwaltung stellt eine zentrale Oberfläche zur Ausführung und Überwachung von ETL-Prozessen bereit. Für den täglichen Betrieb stehen vor allem die Aktionen „Unload“, „Update“ und „Unload & Update“ im Vordergrund. Zusätzlich können Module installiert oder per Upgrade auf den ausgelieferten Stand gebracht werden.

Die Modulübersicht zeigt den Installationsstatus, Versionsinformationen, Datenquellen und Datenbankverbindungen. Der Bereich „Aktueller Lauf“ informiert über den Fortschritt eines gestarteten Prozesses. Die Log-Ausgabe liefert technische Zusatzinformationen und kann bei der Fehleranalyse helfen.

Details und Diagnose ergänzen die Oberfläche um technische Informationen für Support- und Administrationsfälle. Sie unterstützen bei der Analyse, führen aber keine automatischen Reparaturen aus.

= Installation und Verwaltung in der Shell mit Skripten =

== Installation von Modulen ==
Das Kernmodul enthält außer Administrationsabfragen und Tabellen keinerlei Inhalte. Die Inhalte werden in Form von Modulen hinzugefügt. Dazu gibt es vorgefertigte [[Kernmodul_Shellscripte#Modulverwaltung|Installationsscripte]].

=== Architektur von SuperX-Modulen ===
Die folgende Abbildung zeigt die Architektur von Modulen ab Beispiel vom HISCOB-Modul:

{| class="wikitable"
|-
!
!
|-
| Ein Modul besteht auf Datenbankseite aus Abfragen, Hilfstabellen, Datentabellen und Schlüsseltabellen (sowie Prozeduren).
Auf Webserver-Seite können auch XSL-Stylesheets vorhanden sein.
| [[Bild:modularchitektur_cob.png|417x307px]]
|}
Die Abbildung zeigt, dass ein Modul eigene Komponenten nutzt, aber auch auf Teile des Kernmoduls zugreift, z.B. das Orgranigramm - dies macht SuperX zu einem integrierten System. Neben dem Organigramm sind alle anderen Komponenten des Kernmoduls natürlich betroffen, z.B. Themenbaum, Userrechte.
Die Ordnerstruktur eines Moduls spiegelt die Komponenten des Systems wieder. Es gibt je ein Verzeichnis für datentabellen, schluesseltabellen und hilfstabellen.
Die Installation eines Moduls ist in der Dokumentation des jeweiligen Moduls näher beschrieben. Module, die auf dem Kernmodul 2.1 oder höher basieren, haben einen einheitlichen Aufbau.

=== Modulscripte im Kernmodul ===
Seit Version 2.1 werden die Datenbankschemata und Scripte der Module in einem einheitlichen Format zusammengestellt und in einer Datei $SUPERX_DIR/db/module/$MODULNAME/conf/$MODULNAME.xml gespeichert. Das XML-Format hat den Vorteil, dass die Scripte dynamisch für Postgres und Informix erzeugt werden können, und dass die Scripte vereinheitlicht werden. Aus dieser Datei werden die Scripte erzeugt, die das Modul jeweils für Postgres und Informix installieren / updaten /aktualisieren / überprüfen und entfernen. Die folgende Abbildung zeigt das Vorgehen:

{| class="wikitable"
|-
!
!
|-
| Aus der xml-Datei werden die jeweiligen Scripte für die Installation, den Update, die Extraktions-, Transformations- und Ladescripte (ETL) und die Deinstallation erzeugt.
| [[Bild:modulscripte_erzeugen.png|417x371px]]
|}

Die Modul-Scripte liegen als Shellscripte im Verzeichnis $SUPERX_DIR/db/bin, und sind an [[Kernmodul_Shellscripte#Modulverwaltung|anderer Stelle]] im Detail erläutert.

{| class="wikitable"
|-
!
!
|-
| module_install.x -name- -pfad-
z.B.:
module_install.x sos $SOS_PFAD
| Installiert ein Modul, d.h. erzeugt die Tabellen, Views, Funktionen und Abfragen. Die Abfragen werden in den Themenbaum eingehängt.
|-
| module_etl.x -name- -pfad-
z.B.:
module_etl.x sos $SOS_PFAD
| Aktualisiert das Modul, d.h. lädt die Rohdaten, Transformiert sie, und aggregiert die Hilfstabellen. Fehler werden in eine Log-Datei geschrieben, diese kann dann per Mail an einen Admin versandt werden. Wenn das Script erfolgreich durchläuft, wird die Tabelle systeminfo aktualisiert. 
Das Script wird nicht direkt als Cronjob aufgerufen, sondern von einem Shellscript, das die Umgebungsvariablen und Parameter setzt, z.B. cob_update.x.
|-
| module_drop.x -name- -pfad-
z.B.:
module_ drop.x sos $SOS_PFAD
| Entfernt das Modul bzw. die Tabellen, Views, Funktionen und Abfragen.
|-
| module_scripts_create.x -name- -pfad- -Datenbanksystem(optional, INFORMIX, POSTGRES)- -Versionsnr.-
| Erzeugt via XSL-Transformation die jeweiligen Scripte, die in den obigen Scripten aufgerufen werden, z.B. bau_install_ids.sql für das Installationsscript des Baumoduls beim Informix Dynamic Server.
|}

Neben den operativen Scripten erzeugt module_scripts_create.x auch html-Dateien zur Dokumentation eines Moduls in
$SUPERX_DIR/db/module/-Modulname-/conf/-Modulname-.html
(auch als rtf-Datei zu Einbindung in Modul-Dokumentationen) sowie zur Schnittstelle in
$SUPERX_DIR/db/module/-Modulname-/rohdaten/-Modulname-_unload.html
Darüber hinaus werden auch DBForms-Formulare erzeugt.

=== Installation eines Moduls: Allgemeines Vorgehen ===
Das Vorgehen bei der Installation eines Moduls ist standardisiert. Im folgenden eine Kurzbeschreibung, weiter unten finden Sie das Vorgehen am Beispiel des ZUL-Moduls im Detail.
* Entpacken Sie das Modul in $SUPERX_DIR
* Erweiterung der Umgebung in der Datei $SUPERX_DIR/db/bin/SQL_ENV: fügen Sie den Inhalt der jew. Beispieldatei SQL_ENV_-Modulname-.sam in der SQL_ENV an, wenn noch nicht vorhanden, und ändern Sie ggf. Email-Adressen für log- und Fehlermails.
* Entladen der Rohdaten; auch hier müssen vorher Umgebungsvariablen zum Vorsystem angepasst werden 
(Datei $-Modulname-_LOAD_PFAD/-Modulname-_ENV), hier liegt ebenfalls eine *.sam-Datei vor
* Kopieren der Rohdaten nach -Modulpfad-/rohdaten. Neuere SuperX-Module haben dafür vorgefertigte Scripte mit dem Namen -Modulname-_copy.x (z.B. zul_copy.x)
* Installieren Sie das Modul mit -Modulname-_erzeugen.x, z.B. mit zul_modul_erzeugen.x
* Wenn die Installation erfolgreich war, können Sie das Modul aktualisieren mit 
-Modulname-_update.x (ggf. mit Parametern) 
z.B. mit
zul__update.x
d.h. die ETL-Prozesse werden gestartet (s.u.).
* Wenn das Modul erfolgreich aktualisiert ist, wird eine Prüfprozedur gestartet, die die Daten plausibilisiert. Fehler und Warnungen finden Sie in der Datei $-Modulname-_ERRORDAT.
* Starten Sie Tomcat neu. Wenn Tomcat auf einem separaten Server installiert ist, müssen Sie vorher die Datei $SUPERX_DIR/webserver/tomcat/webapps/superx/WEB-INF/dbforms-config.xml dorthin übertragen.
* Schritt 7 wird bei jedem SuperX-Update wiederholt. Nun muss der Entladerhythmus geplant werden, und die Cronjobs werden eingerichtet. Es gibt eine Musterdatei $SUPERX_DIR/db/module/-MODULNAME-/-MODUL-_update_cron.x.sam , benennen sie diese um nach -MODUL-_update_cron.x und fügen Sie das Script in die crontab ein.

==== Allgemeines zum Laden ====
Zunächst müssen die Rohdaten aus dem Vorsystem entladen werden.
Für das Entladen gibt es ferner zwei Modi: Das "Pull"-Verfahren und das "Push"-Verfahren.
* Beim '''"Pull"-'''Verfahren wird einer Benutzerkennung auf dem SuperX-Rechner Zugriffsrecht auf die SOSPOS-Datenbank gegeben, und die Daten werden via TCP/IP aus dem Basissystem entladen. Bei APP / HISinOne als Quellsystem ist "Pull" das Standardvorgehen.
* Beim '''"Push"-'''Verfahren werden die Entladescripte auf den SOSPOS-Rechner kopiert und dort von einer Benutzerkennung auf dem SOSPOS-Rechner ausgeführt. Die Rohdaten müssen dann auf den SuperX-Rechner kopiert werden. Dieses Verfahren klappt bei Informix unter Unix problemlos, bei Entladen aus Postgres müsste das komplette SuperX-Kernmodul installiert werden.
Am einfachsten ist immer das "Pull"-Verfahren, das mit fast allen Quellsystemen funktioniert und wenig Konfiguration auf dem Quellsystem erfordert. Aufgrund von Sicherheitsvorkehrungen oder Netz-Infrastrukturen wählen aber viele Hochschulen das "Push"-Verfahren. Da derzeit Informix /Unix die gängigste Plattform an Hochschulen ist, ist dies auch kein Problem.

==== Einrichtung der Entladescripte ====
Im Push-Verfahren btw. unter SuperX können Sie mitgelieferte Shellscripte nutzen. Das folgende Beispiel des ZUL-Moduls zeigt das Vorgehen:
Die Entladescripte liegen im Verzeichnis $SUPERX_DIR/db/module/zul/rohdaten und lauten je nach Systemversion:
zul_unload.x

Die Scripte laufen nur, wenn die entsprechenden Umgebungsvariablen in der Datei ZUL_ENV (im gleichen Verzeichnis, ein Muster liegt vor in ZUL_ENV.sam) korrekt gesetzt sind, benennen Sie die Musterdatei um nach ZUL_ENV und tragen die richtigen Umgebungsvariablen ein, z.B. den Pfad für $INFORMIXDIR.
'''ZUL_ENV Die Umgebung für Entladescripte aus ZUL-GX(Auszug)'''
##Pfad für Entladedaten:
ZUL_PFAD=.; export ZUL_PFAD
##hier muss Unterverzeichnis unl existieren!

In der ZUL_ENV müssen außerdem folgende Umgebungsvariablen gesetzt werden (defaults sind bereits vorbelegt, aber hier und da müssen Sie sicher ran):
{| class="wikitable"
|-
! Variable
! Erläuterung
|-
|
| '''Nur für Informix gelten:'''
|-
| INFORMIXDIR
| Home-Verzeichnis von Informix
|-
| INFORMIXSERVER
| Name des Informixservers
|-
| ONCONFIG
| Name der onconfig, wenn auf dem SOS-Rechner mehrere Informix-Instanzen laufen
|-
| CLIENT_LOCALE
| Sprachumgebung (wichtig fürs Entladen von Datumsformaten)
|-
| SERVER_LOCALE
| dito
|}

{| class="wikitable"
|-
! Variable
! Erläuterung
|-
|
| '''Nur für Postgres gelten:'''
|-
| PGDATESTYLE
| Datumsformat "German"
|-
| PGPORT
| Port vom Postgres-Server, standardmäßig 5432
|-
| PGHOST
| Hostname oder IP-Adresse vom Postgres-Server
|-
| PGUSER
| Benutzerkennung für Postgres-Server (nur Datenbank, nicht Betriebssystem)
|-
| PGPATH
| Installationsverzeichnis von Postgres, z.B. /usr/local/pgsql
|-
| DB_PROPERTIES
| Pfad zur db-zul.properties-Datei mit den Zugangsparametern für SOSPOS unter Postgres
|-
| LOGGING_PROPERTIES
| Pfad zur Steuerungsdatei mit den Parametern für das Logging beim Entladen, voreingestellt auf ./logging.properties. Normalerweise brauchen Sie hier nichts ändern, wenn beim Entladen Probleme auftauchen, kann man den Level von SEVERE auf INFO oder FINEST ändern, dann werden die konkreten SQLs geloggt. Aber Achtung: wenn keine Fehler mehr auftreten, müssen Sie den Level wieder auf SERVERE ändern, sonst kommen Schlüsselworte in die Logdatei zul_unload.err, die dann bei der Übernahme nach SuperX fälschlicherweise zu Fehlermeldungen führen.
|}
Unter Postgres muss für das "Pull"-Verfahren beim Entladen die Datenbankverbindung in der Datei db-zul.properties eingetragen werden (Muster für Postgres liegt bei in db-zul_pg.properties). Dazu laden Sie einmal die Datei ZUL_ENV mit den obigen Parameter, starten den SuperX-Propadmin (siehe Administrationshandbuch Kernmodul) und richten die Verbindung zum SOSPOS-Server ein. Das Kennwort wird verschlüsselt gespeichert. Danach sind die Entladescripte für Postgres ausführbar.
Hinweis: Anders als Informix hat Postgres hat eine eigene, vom Basissystem unabhängige Benutzerverwaltung. Daher brauchen Sie den User, den Sie zum Entladen aus Postgres nutzen, nicht auf dem SuperX- oder SOSPOS-Rechner auf Betriebssystem-Ebene einrichten. Sie können also z.B. auf dem SuperX-Rechner zum Entladen aus SOSPOS die Kennung sospos des Postgres- Rechners verwenden. Oder Sie richten in der SOSPOS -Datenbank den Benutzer SuperX ein und geben ihm Leserecht auf die Tabellen sowie das Recht, Tabellen und Stored Procedures anzulegen.

{| class="wikitable"
|-
! Variable
! Erläuterung
|-
|
| '''Für alle Platformen gelten folgende Variablen:'''
|-
| ERRORMAIL
| An wen solle eine Logmail verschickt werden, wenn das Entladen nicht geklappt hat? (nur Unix).
|-
| LOGMAIL
| An wen soll immer eine Logmail verschickt werden
|-
| MAILPROG
| Pfad zum ausführbaren Mailprogramm unter Unix, Vorbelegung ist "mail", manche Unixe haben aber auch "mutt" oder "mailx".
|-
|
| Wenn die Rohdaten beim Push-Verfahren nach dem Entladen vom ZUL-Rechner auf den SuperX-Rechner kopiert werden sollen, dann werden für das Script zul_copy.x folgende Umgebungsvariablen benötigt:
|-
| COPY_METHOD
| Programm, das die Dateien kopiert; rsync und scp sind wählbar.
|-
| REMOTE_DIR
| Verzeichnis, in das die Rohdaten auf dem SuperX-Rechner kopiert werden sollen, in der Regel ist dies "/home/superx/db/module/zul/rohdaten"
|-
| REMOTE_USER
| Der Unix-Username auf dem SuperX-Rechner, in der Regel "superx".
|-
| REMOTE_HOST
| Der Rechnername bzw. die IP-Nr. des SuperX-Rechners.
|}
Dann starten Sie das Script zul_unload.x. Wenn es gelaufen ist, müssten die Dateien im unl-Verzeichnis stehen. Prüfen Sie dann bitte, ob dort Dateien mit 0 bytes stehen. Die Logdatei heisst zul_unload.err.

===== Entladen unter Windows =====
Für das Entladen unter Windows gibt es Muster-Dateien im jew. Rohdaten-Verzeichnis, z.B. $SOS_PFAD/rohdaten/sos_unload.bat. Die Einrichtung geschieht dann in [[Kernmodul_Komponentenverwaltung#Java-Client_zum_Entladen_von_Quell-Datenbanken|Java]]. Ans Ende der Datei können Sie noch schreiben:
date /T >superx.datum
Dann wird auch die Datumsdatei geschrieben.

===== Dateitransfer beim Push-Verfahren =====
Wenn Sie das Verzeichnis nicht gemounted haben, müssen das Verzeichnis unl, die zul_unload.err und die superx.datum dann in das Verzeichnis $ZUL_LOAD_PFAD auf dem SuperX-Rechner kopiert werden, ein Script dafür liegt ebenfalls bei (zul_copy.x). Das Entladedatum wird danach in der Textdatei $ZUL_LOAD_PFAD/superx.datum gespeichert; wenn das Script einen Fehler findet, dann wird das vorherige Datum (in der Datei superx.datum.alt) gesetzt.

Für den Transfer der Rohdaten beim Push-Verfahren wird in SuperX die dateibasierte Schnittstelle genutzt. Unter UNIX läßt sich dieser Transfer vollends automatisieren, indem die Programme scp oder rsync auf der Basis des OpenSSH-Pakets genutzt werden. Beide setzen auf das ssh-Protokoll 2 auf und stellen somit einen verschlüsselten Dateitransfer sicher. Auch [[Kernmodul_Komponentenverwaltung#Einrichtung_von_SFTP|sftp]] ist möglich.
In den jeweiligen Modulen wird im Verzeichnis rohdaten eine Beispieldatei mit dem Namen -MODULNAME-_ENV.sam ausgeliefert, die Sie umbenennen können nach -MODULNAME-_ENV. Darin werden am Ende der Datei die Parameter zum Kopieren festgelegt, also die Userkennung REMOTE_USER, der Hostname REMOTE_HOST, und die Methode des Kopierens (COPY_METHOD) sowie die jeweiligen Zielpfade. Diese Umgebungsvariablen werden von dem jeweiligen Script -modulname-_copy.x benutzt.

===== Entfernen der Passworteingabe unter Unix =====
Damit die Passworteingabe unter Unix entfällt, muss man wie folgt vorgehen:
Loggen Sie sich zunächst testweise einmal ein. Wenn Sie z.B. vom COB-Server auf den SuperX-Server kopieren wollen, loggen Sie sich als user cob auf cobhost ein mit 
ssh superx@superxhost
Beim ersten Mal müssen Sie die Sicherheitsabfrage mit "yes" bestätigen.
Erzeugen Sie auf dem Quellrechner einen öffentlichen Schlüssel mittels

ssh-keygen -t ed25519 -C "cob@cobhost"

wobei man eine leere Passphrase vergibt. Der öffentliche Teil dieses Schlüssels (~/.ssh/id_ed25519.pub) muss auf dem Zielrechner in die Datei ~/.ssh/authorized_keys eingefügt werden, ggf. muss die Datei neu erzeugt werden.
Wenn z.B. auf dem COB-Server unter der Kennung cob ein Key wie folgt erzeugt wurde:

;Beispieleintrag eines Public Keys:

ssh-ed25519 AAAAC3N.[hier viele kryptische Zeichen]....4V cob@cobhost

Dann wird genau diese Zeile in der Datei /home/superx/.ssh/authorized_keys angefügt (die Datei kann mehrere PublicKeys enthalten, ein Eintrag pro Absatz).
Achten Sie auch auf Dateirechte: Die Verzeichnisse und Dateien sollten keine Schreibrechte für Gruppen haben. Im Zweifelsfall z.B. für den user superx:
chmod 700 /home/superx/.ssh
chmod 700 /home/superx/.ssh
chmod 600 /home/superx/.ssh/authorized_keys
Danach sollte z.B. der Login vom cobhost als user cob mit ssh superx@superxhost ohne Passworteingabe klappen. Wenn nicht, schalten Sie das Logging mit ssh -v superx@superxhost ein. Eine Möglichkeit ist, dass die PublicKey-Authentifizierung in der Konfigurationsdatei des SSHD (normal /etc/ssh/ssh_config) abgeschaltet ist. Weitere Diagnosen liefert die Datei /var/log/messages.
Sie können außerdem noch einschränken, von welchem Host die obige Authentifizierung ermöglicht wird. Dazu setzen Sie den Parameter "from=*.uni-xy.de" davor, z.B.

{| class="wikitable"
|-
!
!
|-
| Einschränkung "from" 
in authorized_keys
| from="*.uni-xy.de" ssh-rsa AAAAB3Nza…[hier viele kryptische
Zeichen]…pg6VkCc= cob@cobhost
|}

Wenn Sie die Kopiermethode scp benutzen, und die obige "authorized_keys"-Metohde mit PublicKey nicht nutzen wollen, können Sie auch mit Private Keys arbeiten (siehe SSH-Doku). Dazu können sie in der *_ENV-Datei in dem Parameter SCP_OPTS den Verweis auf den private Key setzen.
{| class="wikitable"
|-
!
!
|-
| SCP_OPTS in *_ENV: 
Beispiel COB_ENV
| SCP_OPTS="-p -B -i /home/cob/.ssh/superx_key"
export SCP_OPTS
|}

===== Entfernen der Passworteingabe unter Windows =====
Wenn Sie die ssh-Shell putty aus dem Installationspaket nutzen, haben Sie im Installationsordner auch die Anwendung "puttyGen.exe". Wenn Sie putty als reine Executable nutzen, laden Sie die Anwendung separat herunter. [http://winscp.net/download/puttygen.exe PuttyGen]
* Folgen Sie der Anleitung auf der Seite http://winscp.net/eng/docs/ui_puttygen, um den SSH2-DSA oder RSA Schlüssel zu erzeugen. Für den Schlüssel bitte kein Passwort vergeben, wenn Sie das Tool automatisiert nutzen.
* Den privaten Schlüssel geben Sie in Putty bzw. Winscp im Menü "Session" im Feld "Private Key File" an.
* Der Button "Save public key" ist nicht für OPENSSH unter Linux als Zielserver geeignet. Im folgenden Screenshot sehen Sie den markierten Bereich, den Sie kopieren müssen:
[[Bild:puttygen.png|413x402px]]
* Kopieren Sie Ihren Public Key, den Sie oben mit PuttyGen erzeugt haben, zur Datei "authorized_keys" und kopieren Sie diese in das Verzeichnis ~/.ssh/
* Im Profil unter Connection -> SSH -> Auth -> Credentials geben Sie den Pfad zum privaten Schlüssel in "Private key file" an.
* Bei erneutem Login mit Putty oder Winscp sollte die Passwortabfrage entfallen.

===== Einrichtung von SFTP (Server) =====
Beim Push-Verfahren wird, wenn mit scp oder rsync kopiert wird, eine Login-Shell vorausgesetzt. Wenn dies aus Sicherheitsgründen nicht gewünscht ist bzw. wg. Einsatz von Windows nicht möglich ist, können Sie auch sftp nutzen, dies wird in modernen ssh-Servern mitgeliefert und bietet ebenfalls verschlüsselten Datentransfer. Zur Einrichtung des Servers:
Der SSH-Dienst wird wie folgt konfiguriert (am Beispiel Ubuntu Linux 22.04 LTS) mit dem SFTP-Verzeichnis /home/sftp/-benutzername:

In der Datei /etc/ssh/sshd_config die Zeile auskommentieren:
#Subsystem sftp /usr/lib/openssh/sftp-server
und stattdessen:
Subsystem sftp internal-sftp
Match Group sftponly
ChrootDirectory /home/sftp/%u
ForceCommand internal-sftp
AllowTcpForwarding no

Danach starten Sie den SSH-Dienst neu:
service ssh restart

Dann legen Sie die Gruppe "sftponly" an:
groupadd sftponly
und dann den Unix-User an, und geben ihm die Gruppe "sftponly". Hier ein Script:
#!/bin/sh
SFTPUSERNAME=$1
mkdir -p /home/sftp/$SFTPUSERNAME
useradd -b /home/sftp -s /bin/false -G sftponly $SFTPUSERNAME
chown root:root /home/sftp/$SFTPUSERNAME
chmod 755 /home/sftp/$SFTPUSERNAME
mkdir -p /home/sftp/$SFTPUSERNAME/incoming
chown $SFTPUSERNAME:sftponly /home/sftp/$SFTPUSERNAME/incoming

Danach legen Sie mit
passwd $SFTPUSERNAME
ein Passwort fest.

Der User kann sich dann nicht mehr mit ssh einloggen, nur noch mit sftp, und landet beim Login in /home/$KENNUNG, in einem "chroot-Käfig", und der User kann mit SFTP in den Ordner "incoming" schreiben. Zum Testen geben Sie ein:
sftp $KENNUNG@-Host-

Wenn beim SFTP Login die Meldung kommt:
client_loop: send disconnect: Broken pipe
müssen Sie darauf achten dass das Home-Verzeichnis des Users nicht dem User gehört, sondern root.

Wenn der Login klappt, können Sie nach dem [[Kernmodul_Komponentenverwaltung#Entfernen_der_Passworteingabe_unter_Unix|oben]] beschriebenen Verfahren die Passworteingabe durch PublicKey-Authentifizierung ersetzen.

===== Einrichtung von SFTP =====
Für das Kopieren der Rohdaten können Sie im Kopierscript "-modulname-_copy.x" auch sftp-Kommandos nutzen. Sie müssen nur in der ENV-Datei die Variable
COPY_METHOD=sftp
setzen. Alle anderen Variablen und Mechanismen wie z.B. [[Kernmodul_Komponentenverwaltung#Entfernen_der_Passworteingabe_unter_Unix|Entfernen der Passworteingabe]] entsprechen denen von SCP / SSH (s.o.).
Spezielle Optionen fürs sftp können Sie in der Umgebungsvariable SFTP_OPTS setzen. Es kann z.B. sein, dass das Kopieren großer Dateien in einen Timeout läuft. Bei CSV bietet es sich an, die Dateien zu komprimieren, sie können also setzen:
SFTP_OPTS="-oCompression=yes"
export SFTP_OPTS
Danach wiederholen Sie das kenn_copy.x
Dies ist nur ein Beispiel. Weitere Optionen für SFTP entnehmen Sie der manpage.
Das Kopieren mit sftp klappt übrigens auch unter Windows z.B. mit dem Programm [http://winscp.net/eng/docs/lang:de winscp]. Dies wird im folgenden erläutert.

===== Einrichtung von SFTP unter Windows =====
Unter Windows ist das Standardprogramm für SFTP die Anwendung [http://winscp.net/eng/docs/lang:de winscp]. Sie können die Passworteingabe analog zu Putty [[Kernmodul_Komponentenverwaltung#Entfernen_der_Passworteingabe_unter_Windows|entfernen]]. Danach können Sie eine Session erzeugen:

[[Bild:winscp1.png|517x364px]]

Im Feld "Private key file" geben Sie den private key ein, den Sie [[Kernmodul_Komponentenverwaltung#Entfernen_der_Passworteingabe_unter_Windows|oben]] erzeugt haben. Klicken Sie dann auf "Save session", und geben Sie einen kurzen, sprechenden Namen ohne Leerzeichen oder Umlaute, z.B. "superx@vmmulti1"
Sie müssen nun die Verzeichnisse lokal und remote in der Winscp-Session speichern, im Menüpunkt "Directories":

[[Bild:winscp2.png|517x359px]]

Vergessen Sie auch hiernach nicht, die Session zu speichern.
Danach testen Sie einmal den Zugang. Wenn das klappt können Sie Winscp auch für die Kommandozeile automatisieren. Sie erzeugen zunächst eine Textdatei mit den Kommandos für Winscp, dies enthält auch die zu übertragenden Dateien. Der Aufbau der Datei ist wie folgt:
open -Sessionname-
# Upload the file to current working directory
put -Datei-
# Disconnect
close
# Exit WinSCP
exit

Die zu übertragenden Dateien sind in der Musterdatei des jew. Moduls in rohdaten/-Modulname-_sftp.txt aufgelistet, Sie müssen lediglich
* den "/" durch einen "\" ersetzen
* das Entladeprotokoll -Modulname-_unload.err und die Datumsdatei superx.datum hinzufügen
Hier ein Beispielscript fürs das Studierenden-Modul:
open superx@vmmulti1
# Change remote directory
# Upload the file to current working directory
put sos_unload.err
put superx.datum
put unl\konstanten.unl
put unl\sos_studenten.unl
put unl\sos_hzb.unl
put unl\sos_faecher.unl
put unl\sos_pord_to_stg.unl
put unl\sos_pruefungenext.unl
put unl\sos_pruefungen.unl
put unl\sos_lab_astat_attributes.unl
put unl\sos_stud_loe.unl
put unl\sos_faecher_ext.unl
put unl\sos_faecher_kontrolle.unl
put unl\sos_pruefungen_kontrolle.unl
put unl\sos_anschri.unl
put unl\sos_parstg.unl
put unl\sos_hsnr.unl
put unl\semester.unl
put unl\cif.unl
put unl\cifx.unl
put unl\k_pvers.unl
put unl\k_stg.unl
put unl\k_stgext.unl
put unl\k_abstgv.unl
put unl\sos_pord.unl
put unl\sos_dipl.unl
put unl\sos_minder.unl
put unl\sos_stud_d.unl
put unl\sos_pords.unl
put unl\sos_porg.unl
put unl\sos_labzuord.unl
put unl\sos_pnrzuord.unl
put unl\sos_gewichtungsvariante.unl
put unl\sos_gewichtungregel_filter.unl
put unl\sos_gewichtungregel.unl
put unl\personattribute.unl
put unl\personattributetype.unl
put unl\personattribute_value_list.unl
put unl\stu_update_prot.unl
put unl\exa_update_prot.unl
put unl\sos_accredited_ects.unl
put unl\sos_pord_orgeinheit.unl
# Disconnect
close
# Exit WinSCP
exit

Die Datei hat z.B. den Namen winscp_example_script.txt. Dann können Sie das Script aufrufen mit dem DOS-Kommando:
winscp /script=-Pfad zu-\winscp_example_script.txt

Hier ein Screenshot wie das dann aussieht:

[[Bild:winscp3.png|609x337px]]

Das DOS-Kommando läßt sich dann über die Windows-Taskverwaltung automatisieren.

===== Java-Client zum Entladen von Quell-Datenbanken =====
Zum Entladen aus dem operativen Vorsystem wird unter Informix dbaccess genutzt. Unter Postgres wird generell der SuperX-JAVA-Client zum Entladen genutzt, denn SuperX benötigt ein spezielles, an Informix angepasstes [[Kernmodul_Komponentenverwaltung#Format_der_Unload_Dateien_CSV|CSV-Format]], das sich mit Bordmitteln von Postgres (copy-Befehl) nicht erzeugen lässt. Es kann aber auch sinnvoll sein, aus der Informix-Datenbank mit SuperX-JAVA-Client zu entladen, z.B. wenn Sie kein UNIX-dbaccess auf dem Vorsystem installiert haben.

Wenn Sie das jew. operative Vorsystem im PUSH-Verfahren entladen wollen, d.h. die Rohdaten werden auf dem Vorsystem entladen und auf den SuperX-Rechner kopiert, dann müssen Sie spezielle Vorkehrungen treffen. SuperX nutzt generell zum Entladen eigene Java-Klassen. Beim Entladen im PULL-Verfahren sind diese Klassen vorhanden, denn die Entladeroutine läuft auf dem SuperX Rechner. Wenn Sie aber PUSH nutzen wollen, werden die SuperX-Java-Klassen auf dem Liefersystem benötigt, und die Entladeroutine muss konfiguriert sein. Im Folgenden nutzen wir das Beispiel "Entladen im Push-Verfahren aus SVA-GX unter Postgres". Gehen Sie dazu wie folgt vor:
* Kopieren Sie die Dateien
** superx*jar
** postgresql-*.jar
** jfor-0.7.2rc1.jar
* vom SuperX-Rechner im Verzeichnis $SUPERX_DIR/tomcat/webapps/superx/WEB-INF/lib auf den Quellrechner in ein Unterverzeichnis lib unter rohdaten (z.B. /home/sva/superx/rohdaten/lib). In rohdaten liegt die bisherige Entladeroutine (z.B. sva_unload.x).
* Kopieren Sie die *_ENV.sam -Datei nach *_ENV, also hier SVA_ENV.sam nach SVA_ENV
* Fügen Sie dann folgenden Passus in die Umgebungs-Datei der Entladeroutine, hier also SVA_ENV:
#Pfad zu den SuperX-Java-Libraries
#Der JDBC_CLASSPATH enthält alles, was der jdbc-Client in superx für den Datenbankzugriff braucht.
#jfor*.jar, postgresql*.jar
JDBC_CLASSPATH="$SVA_LOAD_PFAD/lib/superx5.0.jar:$SVA_LOAD_PFAD/lib/postgresql-42.2.19.jar:$SVA_LOAD_PFAD/lib/jfor-0.7.2rc1.jar"
export JDBC_CLASSPATH

Wenn dann noch die Variablen [[Kern_Installation_Upgrade#Anpassen_der_Datenbankparameter_db.properties|DB_PROPERTIES]] und LOGGER_PROPERTIES korrekt gesetzt sind, kann die Entladeroutine bei SX_CLIENT=jdbc (Wenn Sie unter Windows entladen, oder Informix ohne dbaccess entladen wollen) oder SX_CLIENT=psql (wenn Sie Postgres unter UNIX nutzen) mit Java entladen.

Danach können Sie das Entladescript ausführen:
sva_unload.x
Die Logdatei lautet sva_unload.err

Zum Kopieren der Rohdaten zum SuperX-Server passen Sie folgende Variablen an:

{| class="wikitable"
|-
! Variable
! Erläuterung
|-
|
| Wenn die Rohdaten beim Push-Verfahren nach dem Entladen vom SVA-Rechner auf den BI-Rechner kopiert werden sollen, dann werden für das Script sva_copy.x folgende Umgebungsvariablen benötigt:
|-
| COPY_METHOD
| Programm, das die Dateien kopiert; rsync, [[Kernmodul_Komponentenverwaltung#Einrichtung_von_SFTP|sftp]] und scp sind wählbar [Achtung: diese müssen dann betriebssystemseitig installiert sein].
|-
| REMOTE_DIR
| Verzeichnis, in das die Rohdaten auf dem BI-Rechner kopiert werden sollen, in der Regel ist dies "/home/superx/db/module/sva/rohdaten"
|-
| REMOTE_USER
| Der Unix-Username auf dem BI-Rechner, in der Regel "tomcat" oder "superx".
|-
| REMOTE_HOST
| Der Rechnername bzw. die IP-Nr. des BI-Rechners.
|}
Danach starten Sie
sva_copy.x
Die Logdatei lautet sva_copy.err

Weitere Entladeparameter werden in den modulspezifischen Administrationshandbüchern beschrieben.
{{Hinweis|Bei neuen SuperX-Versionen reicht es in der Regel, die modulspez. Dateien auszutauschen, also hier sva_unload.* etc.}}

== Update eines Moduls: Allgemeines Vorgehen ==
Wenn das Entladen aus dem Vorsystem geklappt hat (sofern es ein Vorsystem gibt), können Sie die Daten laden. Zum Update bzw. zum Laden der Rohdaten gehen in das Verzeichnis $SUPERX_DIR/db/module/-Modulname- und führen das Script aus:
-Modulname-_update.x
Die Logdatei lautet L_-Modulname-_UPDATE.log, im Mandantenfähigen Betrieb "L_-Modulname-_UPDATE-MANDANTID-.log".
Für die Aufnahme der Laderoutine in die crontab gibt es im gleichen Verzeichnis Musterscripte nach dem Namensmuster:
-Modulname-_update_cron.x
Je nach Push/Pull-Szenario können Sie auch den Unload darin starten oder nicht.

=== Modulupdate in mandantenfähigen Installationen ===
Der Modulupdate in mandantenfähigen Installation findet in einer SuperX-Installation statt, allerdings werden die einzelnen Scripte mit unterschiedlichen Umgebungsvariablen, wie sie in SQL_ENV.-MANDANTID- definiert ist, z.B. SQL_ENV.FHRO.
In der SQL_ENV.-MANDANTID- werden unterschiedliche Pfade für den jeweiligen *_LOAD_PFAD gesetzt, wobei in der Regel die Mandandid ein Unterverzeichnis vom "normalen" LOAD_PFAD ist. So ist z.B. beim COB-Modul folgender Pfad anzusetzen:
Normale SuperX-Installation:
COB_LOAD_PFAD=$SUPERX_DIR/db/module/cob/rohdaten
Mandantenfähige SuperX-Installation:
COB_LOAD_PFAD=$SUPERX_DIR/db/module/cob/rohdaten/FHRO
Unterhalb von FHRO befindet sich noch einmal die Entladeroutine sowie das Unterverzeichnis unl mit den Rohdaten. Dieses Verzeichnis FHRO kann der Einfahheit halber auch ein symbolischer Link auf den gemounteten COB-Rechner sein.
Durch Setzen der Mandantennummer in der Umgebungsvariable MANDANTID in der jeweiligen SQL_ENV des Mandanten werden die ETL-Scripte anders ausgeführt: Die Logdateien werden jeweils mit der Mandantennummer versehen (z.B. L_cob_updateFHRO.log), damit die Übersicht nicht verloren geht und der gleichzeitige Update mehrerer Mandanten in eine rsuperX-Installation möglich ist.
Außerdem können weitreichende Steuerungsmechanismen im Modulupdate eingesetzt werden: Nach jedem ETL-Schritt können optional mandantenspezifische Scripte aufgerufen werden. Diese müssen folgende Namenskonvention einhalten:
-Scriptname-_-MANDANTID-.sql
Also für eine hochschulspezifische Transformation im COB-Modul des Mandanten FHRO wird eine Datei namens
cob_trans_FHRO.sql
mit entsprechenden SQL-Anweisungen angelegt.

=== Format der Unload Dateien CSV ===
Generell gilt das Prinzip, daß Daten vom Vorsystem in CSV entladen werden, und dann in sog. Ladetabellen hochgeladen werden. Da CSV je nach DBMS unterschiedlich implementiert wird, hier eine kurze Beschreibung des Formats, das im wesentlichen den Vorgaben von Informix LOAD entspricht:
* Zeichenformat: UNIX LATIN1 oder UTF-8
* Feldtrenner: ^
* Satztrenner: Feldtrenner + UNIX NEWLINE
* Zeilenschaltung: Umbrüche innerhalb von Textfeldern sind als \ + NEWLINE codiert
* Feldtrenner, die im Textfeld vorkommen, werden mit "\" maskiert. Ebenso das Zeichen "\" selbst
* Die Datumsformate sind bei Datumsfeldern immer im deutschen Format (DD.MM.YYYY) vorgesehen
* Boolean-Werte werden durch "true" oder "false" codiert
* Der Dezimaltrenner ist ".", kein 1000-er Punkt bei Zahlen.
* Leerstrings und Leerzeichen werden als " " (Leerzeichen) exportiert.

== Upgrade eines Moduls: Allgemeines Vorgehen ==
Zum Upgrade bzw. zum Zurücksetzen des Moduls auf den Auslieferungszustand entpacken Sie das Paket in $SUPERX_DIR und gehen in das Verzeichnis $SUPERX_DIR/db/module/-Modulname-/upgrade und führen das Script aus:
-Modulname-_upgrade.x
Ausnahme: beim Kernmodul gibt es i.d.R. ein spezielles [[Kern_Installation_Upgrade#Standardvorgehen_beim_Upgrade|Upgrade Script]].

Die Logdatei lautet upgrade.log, im Mandantenfähigen Betrieb "upgrade-MANDANTID-.log".

Wenn Sie einen separaten Tomcat-Rechner betreiben, müssen Sie das Paket dort ebenfalls entpacken, und vom Datenbankserver die Datei $SUPERX_DIR/webserver/tomcat/webapps/superx/WEB-INF/dbforms-config.xml an die gleiche Stelle auf den Tomcat Rechner kopieren. Ein nochmaliges Ausführen des Upgrade Scriptes ist nicht nötig, weil dies nur die Datenbank betrifft.

== Hochschulspezifische Anpassung eines Moduls ==
=== Dateibasierte hochschulspezifische Anpassung ===
Nach der Installation bzw. beim Upgrade können Sie hochschuleigene SQL Scripte ausführen lassen. Erzeugen Sie dazu eine Datei
$SUPERX_DIR/db/module/-Modulname-/conf/customize.sql
bei Mandantenbetrieb
$SUPERX_DIR/db/module/-Modulname-/conf/customize-MANDANTID-.sql
und füllen Sie diese mit einem beliebigen Inhalt. Das Script wird beim Upgrade des Moduls automatisch am Ende ausgeführt.
=== Datenbankbasierte hochschulspezifische Laderegeln ===
Eine Laderoutine gliedert sich in die Schritte
#Unload: Entladen der CSV Dateien aus dem jew. Vorsystem
#Load: Upload der CSV Dateien
#Trans: Transformation der Daten
#Aggr: Aggregation der Daten
#Test: Test der Daten
#System: Standdatum bei Erfolg aktualisieren
Es ist möglich über sog. "Preparation"- oder "Finalize"-[[Kernmodul_Shellscripte#Hochschulspezifische_Transformationen_im_ETL-Prozess|Scripte]] die Laderoutine am Ende von LOAD bzw. TRANS anzupassen. Dieses Verfahren ist weiterhin möglich, ist aber bzgl. Clustering und Schreibzugriff recht unflexibel.

Es ist auch möglich im Browser hochschulspezifische Scripte am Ende des jeweiligen Schrittes einer Laderoutine anzulegen. Dies funktioniert so: Die Laderoutine führt zunächst den allgemeinen, von uns vorgegebenen Ladeschritt aus. Wenn dann eine Repository-Variable mit einem gewissen Namensschema existiert, wird sie ausgeführt. Das Namensschema lautet
<source lang="xml">
<<Kürzel der Komponente>>_<<Ladeschritt>>_CUSTOM
</source>.
* Bei Hauptladeroutinen ist dies
*# Laden: '''Kürzel der Komponente'''_load_CUSTOM, z. B. sos_load_CUSTOM
*# Transformation: '''Kürzel der Komponente'''_trans_CUSTOM, z. B. sos_trans_CUSTOM
*# Aggregation: '''Kürzel der Komponente'''_aggr_CUSTOM, z. B. sos_aggr_CUSTOM
* Bei Unterladeroutinen ist dies '''Kürzel der Komponente'''_'''ID des Ladeschritts'''_CUSTOM, also z. B. cob_trans_fin_busa_CUSTOM für die Unterladeroutine "Lade Buchungen aus FIN"

Um eine Variable neu einzurichten:
* Gehen Sie in den BI-Standardberichten auf Administration/Hochschul-Repository.
* Wählen Sie das jeweilige Sachgebiet und schicken Sie das Formular ab.
* Klicken Sie bei einer Beispielzeile auf '''Bearbeiten'''.
* Im neuen Fenster klicken Sie oben ganz rechts auf das Symbol '''Datensatz kopieren'''.
* Definieren Sie die Variable z. B.
** als Variablenname die ID z. B.: fin_load_CUSTOM
** Art der Variable: ein für Sie sprechender Schlüssel mit Modulkürzel, z. B. "fin_Laderegel"
** als Inhalt der Variable die gewünschten Befehle, z. B.
<source lang="sql">
update fin_buch_neu set ch110_institut=buchungsab_fb where length(buchungsab_fb)=5;
</source>
** aktiv=1
** gültig seit 1.1.1900
** gültig bis 1.1.3000
* Klicken Sie oben rechts auf das Häkchen-Symbol für '''Datensatz einfügen'''.
* Schließen Sie das Fenster.

Analog können Sie auch die [[Kernmodul_Komponentenverwaltung#Dateibasierte_hochschulspezifische_Anpassung|customize]]-Regeln" ins Repository verlagern. Hier heißt die Variable z.B. fin_install_CUSTOM.

== Entfernen eines Moduls ==
Wenn Sie ein Modul nicht mehr benötigen, starten Sie das Script 
$SUPERX_DIR/db/module/-Modulname-/-Modulname-_modul_entfernen.x. 
Dieses Script löscht alle Tabellen, Prozeduren und Abfragen aus der Datenbank, und löscht auch die Einträge im Themenbaum. Danach können Sie den Pfad $SUPERX_DIR/db/module/-Modulname-löschen.
Wenn Sie nur die Inhalte der Daten- und Hilfstabellen des Moduls löschen wollen (z.B. aus Datenschutzgründen), ohne das ganze Modul zu deinstallieren, können Sie dies mit folgendem Befehl tun:
DOSQL $SUPERX_DIR/db/module/-Modulname-/-Modulname-_purge_pg.sql (für Postgres) 
bzw. 
DOSQL $SUPERX_DIR/db/module/-Modulname-/-Modulname-_purge_ids.sql (für Informix)

Kernmodul Komponentenverwaltung

2026-07-13T06:51:43Z

Andrek:

Die Komponentenverwaltung im Kernmodul kann je nach Aufgabe über die Browseroberfläche oder über Shell-Skripte erfolgen.

Bisher wurden die Installation, Deinstallation, Aktualisierung und das Upgrade von Modulen überwiegend über Skripte in der Shell durchgeführt. Ab Kernmodul 6.0 steht zusätzlich eine Komponentenverwaltung über die Browseroberfläche zur Verfügung. Diese Browseroberfläche wird im Folgenden als SuperX ETL Manager beschrieben.

Der SuperX ETL Manager ist vor allem für die Ausführung und Überwachung von ETL-Prozessen sowie für Modul-Upgrades vorgesehen. Die Installation und Deinstallation von Modulen stehen dort bisher nicht zur Verfügung und werden weiterhin über die Shell-Skripte durchgeführt.

Der folgende Artikel ist daher in zwei Bereiche gegliedert: Zuerst wird die Nutzung des SuperX ETL Managers beschrieben. Anschließend folgt die Dokumentation zur Installation und Verwaltung von Modulen mit Skripten.

= Komponentenverwaltung im Browser: SuperX ETL Manager =
Der SuperX ETL Manager dient dazu, ETL-Prozesse der installierten SuperX-Module über die Weboberfläche auszuführen und zu überwachen. Er bietet eine zentrale Übersicht über installierte Module, verfügbare Aktionen, Versionsinformationen, Datenquellen, den aktuellen Lauf sowie technische Zusatzinformationen für die Fehlersuche.

Der Schwerpunkt der Oberfläche liegt auf dem täglichen Betrieb: Anwenderinnen und Anwender können Laderoutinen starten, den aktuellen Stand eines Laufs verfolgen und bei Bedarf die Log-Ausgabe einsehen. Technische Detail- und Diagnoseinformationen stehen ebenfalls zur Verfügung, sind aber vor allem für Administratorinnen und Administratoren oder den Support gedacht.

[[Bild:SuperX_ETL_Manager_Uebersicht.png|Gesamtübersicht des SuperX ETL Managers mit Modulübersicht, Filterbereich, Aktionsbuttons und aktuellem Lauf.]]

== Aufbau der Oberfläche ==

Die Oberfläche besteht im Wesentlichen aus folgenden Bereichen:

* Filterbereich
* Modulübersicht
* Aktionsbuttons pro Modul
* Bereich „Aktueller Lauf“
* Log-Ausgabe
* Details-Bereich
* Diagnose-Bereich

Über den Filterbereich kann die angezeigte Modulliste eingeschränkt werden. Die Modulübersicht zeigt die wichtigsten Informationen zu den vorhandenen Modulen. Über die Aktionsbuttons können ETL-Prozesse gestartet werden. Der Bereich „Aktueller Lauf“ zeigt den zuletzt gestarteten oder aktuell laufenden Prozess an.

Die Bereiche „Details“ und „Diagnose“ liefern zusätzliche technische Informationen. Sie sind hilfreich für Supportfälle, aber für die normale Bedienung nicht zwingend erforderlich.

== Modulübersicht ==

Die Modulübersicht zeigt die installierten bzw. erkannten Module mit ihren wichtigsten Eigenschaften.

{| class="wikitable"
! Spalte
! Bedeutung
|-
| Modul
| Zeigt den Namen und das technische Kürzel des Moduls, zum Beispiel „Administration“ mit dem Kürzel „kern“ oder „Kennzahlen“ mit dem Kürzel „kenn“.
|-
| Status
| Zeigt, ob das Modul installiert ist.
|-
| Versionen
| Zeigt die installierte Version und die verfügbare Version des Moduls.
|-
| Letztes Update
| Zeigt den Zeitpunkt des letzten bekannten Updates.
|-
| Datenquelle
| Zeigt, aus welcher Datenquelle das Modul seine Daten bezieht oder auf welcher Datenbasis der ETL-Prozess arbeitet.
|-
| DB-Verbindung
| Zeigt, ob die Verbindung zur Datenbank bzw. Datenquelle aktuell erreichbar ist.
|-
| Aktionen
| Zeigt die verfügbaren Aktionen für das jeweilige Modul.
|}

=== Versionen ===

In der Spalte „Versionen“ werden zwei Werte angezeigt:

* installierte Version
* verfügbare Version

Die installierte Version beschreibt den Stand, der aktuell in der Datenbank installiert ist. Die verfügbare Version beschreibt den ausgelieferten Stand des Moduls, der in der Installation vorliegt.

Wenn die verfügbare Version höher ist als die installierte Version, sollte in der Regel ein Upgrade des Moduls durchgeführt werden. Dadurch werden die Datenstrukturen des Moduls auf den ausgelieferten Stand aktualisiert.

=== Datenquelle ===

Die Datenquelle gibt an, aus welchem System ein Modul seine Daten bezieht oder auf welcher Datenbasis es arbeitet.

SuperX ist ein Data Warehouse. Viele Module übernehmen Daten aus externen vorsystemen. Beispiele für solche Datenquellen sind:

* cob für Kostenrechnung
* mbs für Finanzrechnung, Inventar oder Gebäude/Räume/Flächen
* sva für Personal- und Stelleninformationen
* hisinone bei entsprechend angebundenen Modulen

Daneben gibt es Module, die auf bereits in SuperX vorhandene Daten zurückgreifen. In solchen Fällen wird als Datenquelle „SuperX“ angezeigt. Das betrifft vor allem Module, die modulübergreifend, auswertungsorientiert oder spezialisiert auf vorhandene SuperX-Daten zugreifen.

Beispiele hierfür können sein:

* kenn für Kennzahlen
* man für Managementberichte
* erfolg für Studienverlauf bzw. Erfolgsbetrachtungen
* gang für Studiengänge

Die Datenquelle „SuperX“ bedeutet also nicht, dass keine Daten verarbeitet werden. Sie zeigt an, dass die Verarbeitung auf Daten basiert, die bereits im SuperX-System vorhanden sind.

== Aktionen ausführen ==

Die verfügbaren Aktionen hängen vom jeweiligen Modul ab. Nicht jedes Modul unterstützt alle Aktionen. Wenn eine Aktion nicht verfügbar ist, wird der entsprechende Button nicht angezeigt oder ist nicht aktiv.

[[Bild:SuperX_ETL_Manager_Aktionsbuttons.png|Modulzeile mit den Aktionsbuttons Unload, Update, Unload & Update und Upgrade.]]

=== Unload ===

Die Aktion „Unload“ entlädt Daten aus einem angebundenen Vorsystem, sofern für das Modul ein Vorsystem angebunden ist.

Der Unload dient dazu, Daten aus der jeweiligen Datenquelle bereitzustellen, damit sie anschließend in SuperX verarbeitet werden können. Je nach Modul und Einrichtung kann der Unload auch dazu dienen, Daten für eine weitere Verarbeitung oder Übertragung bereitzustellen.

=== Update ===

Die Aktion „Update“ lädt vorhandene Rohdaten in SuperX ein und führt die Hauptladeroutine des Moduls aus.

Dies ist in vielen Fällen die wichtigste Aktion für den täglichen Betrieb. Beim Update werden die vorhandenen Rohdaten verarbeitet und die zugehörigen SuperX-Tabellen aktualisiert.

=== Unload & Update ===

Die Aktion „Unload & Update“ führt zuerst den Unload und anschließend das Update aus.

Diese Aktion ist sinnvoll, wenn neue Daten aus einem angebundenen Vorsystem entladen und direkt anschließend in SuperX verarbeitet werden sollen.

=== Upgrade ===

Die Aktion „Upgrade“ führt eine Modulaktualisierung durch. Dabei werden die Datenstrukturen des Moduls auf den ausgelieferten Stand gebracht.

Ein Upgrade sollte ausgeführt werden, wenn eine neue verfügbare Version angezeigt wird oder wenn dies im Rahmen eines Modulupdates erforderlich ist.

== Sonderfall Kennzahlen-Modul ==

Beim Kennzahlen-Modul „kenn“ ist die Verarbeitung etwas anders als bei typischen Modulen mit externem Vorsystem.

Die Datenquelle ist hier in der Regel „SuperX“. Das bedeutet, dass die Kennzahlen nicht primär aus einem externen Fremdsystem entladen werden. Stattdessen basiert die Verarbeitung auf Daten, die bereits in SuperX vorhanden sind.

Für den täglichen Betrieb ist beim Kennzahlen-Modul daher häufig vor allem die Aktion „Update“ relevant. Dabei werden die Kennzahlen auf Basis der vorhandenen SuperX-Daten neu berechnet bzw. aktualisiert.

Die Aktion „Unload“ kann beim Kennzahlen-Modul eine andere Bedeutung haben als bei klassischen Vorsystem-Modulen. Sie kann dazu dienen, Kennzahlen für ein anderes System bereitzustellen, zum Beispiel:

* für ein hochschulübergreifendes SuperX
* für Vergleichssysteme
* für landesweite Auswertungen oder Berichtssysteme

Die kombinierte Aktion „Unload & Update“ ist beim Kennzahlen-Modul daher nicht immer die wichtigste Aktion. In vielen Installationen wird das Update gezielt über die Oberfläche ausgeführt, während Export- oder Übertragungsprozesse über automatische Abläufe wie Cronjobs gesteuert werden können.

== Aktueller Lauf ==

Der Bereich „Aktueller Lauf“ zeigt Informationen zum zuletzt gestarteten oder aktuell laufenden ETL-Prozess.

Typische Informationen sind:

* JobExecutionId
* Name des gestarteten Jobs
* Status
* Fortschritt
* Anzahl der ausgeführten Schritte
* Log-Ausgabe

[[Bild:SuperX_ETL_Manager_Aktueller_Lauf.png|Bereich „Aktueller Lauf“ mit JobExecutionId, Status, Fortschritt und Log-Ausgabe.]]

=== Status ===

Der Status zeigt den aktuellen Zustand des Laufs. Häufige Statuswerte sind:

{| class="wikitable"
! Status
! Bedeutung
|-
| STARTING
| Der Lauf wird gestartet.
|-
| STARTED
| Der Lauf wurde gestartet und wird ausgeführt.
|-
| COMPLETED
| Der Lauf wurde erfolgreich abgeschlossen.
|-
| FAILED
| Der Lauf ist mit einem Fehler abgebrochen.
|-
| STOPPED
| Der Lauf wurde gestoppt.
|}

=== Fortschritt ===

Der Fortschritt zeigt, wie viele Prozessschritte bereits abgearbeitet wurden. Er ist als technischer bzw. prozessbezogener Fortschritt zu verstehen.

Wichtig ist: Der Fortschrittswert ist keine genaue Zeitprognose.

Ein Lauf kann schnell auf eine hohe Prozentzahl springen und dort längere Zeit stehen bleiben, wenn ein einzelner Verarbeitungsschritt besonders lange dauert. Umgekehrt können viele kleine Schritte sehr schnell nacheinander abgeschlossen werden. Die Prozentanzeige beschreibt daher den Abarbeitungsstand der Prozessschritte, nicht die tatsächlich vergangene oder verbleibende Zeit.

Beispiel:

Ein Lauf kann bereits 80 % anzeigen, obwohl noch ein größerer Verarbeitungsschritt aussteht. Ebenso kann ein Lauf am Anfang längere Zeit bei einer niedrigen Prozentzahl stehen bleiben, wenn ein früher Prozessschritt besonders umfangreich ist.

== Log-Ausgabe ==

Die Log-Ausgabe zeigt technische Informationen zum ausgeführten ETL-Prozess. Sie kann helfen, den Ablauf nachzuvollziehen und bei Problemen erste Hinweise zu erhalten.

Die Log-Ausgabe ist vor allem für Supportfälle hilfreich. Für eine tiefergehende Fehleranalyse sind in der Regel administrative Kenntnisse erforderlich. Je nach Fehler müssen zusätzlich Serverlogs, Datenbankinhalte, Moduldateien oder Systemkonfigurationen geprüft werden.

Wenn die Log-Ausgabe nicht sofort erscheint, kann sie über „Log laden“ erneut abgefragt werden. Gerade bei umfangreichen Läufen kann es vorkommen, dass die Log-Ausgabe erst kurze Zeit nach Abschluss vollständig verfügbar ist.

== Typische Nutzungsszenarien ==

=== Bereits vorhandene Rohdaten verarbeiten ===

Wenn die Rohdaten bereits vorhanden sind und lediglich erneut verarbeitet werden sollen, wird in der Regel die Aktion „Update“ verwendet.

Beispiel:

* Rohdaten liegen bereits im System vor
* Berechnungen oder Aggregationen sollen neu ausgeführt werden
* die SuperX-Tabellen des Moduls sollen aktualisiert werden

Geeignete Aktion:

<pre>
Update
</pre>

=== Neue Daten aus einem Vorsystem übernehmen und verarbeiten ===

Wenn neue Daten aus einem externen Vorsystem übernommen und anschließend verarbeitet werden sollen, kann die Aktion „Unload & Update“ verwendet werden.

Dabei werden zunächst die Daten aus dem Vorsystem entladen. Anschließend werden die Daten durch das Update in SuperX verarbeitet.

Geeignete Aktion:

<pre>
Unload & Update
</pre>

=== Nur Daten aus einem Vorsystem entladen ===

Wenn Daten aus einem Vorsystem entladen werden sollen, ohne direkt anschließend die Laderoutine auszuführen, kann die Aktion „Unload“ verwendet werden.

Geeignete Aktion:

<pre>
Unload
</pre>

=== Modul auf den ausgelieferten Stand aktualisieren ===

Wenn eine neue verfügbare Version angezeigt wird, sollte ein Upgrade geprüft bzw. durchgeführt werden.

Geeignete Aktion:

<pre>
Upgrade
</pre>

=== Kennzahlen innerhalb von SuperX aktualisieren ===

Beim Kennzahlen-Modul „kenn“ werden die Daten in der Regel aus SuperX selbst bezogen. Wenn die Kennzahlen neu berechnet oder aktualisiert werden sollen, ist häufig die Aktion „Update“ die passende Aktion.

Geeignete Aktion:

<pre>
Update
</pre>

=== Kennzahlen für ein anderes System bereitstellen ===

Wenn Kennzahlen für ein anderes System bereitgestellt werden sollen, kann beim Kennzahlen-Modul die Aktion „Unload“ relevant sein.

Dies kann zum Beispiel für hochschulübergreifende Auswertungen, Vergleichssysteme oder landesweite Berichtssysteme genutzt werden.

Geeignete Aktion:

<pre>
Unload
</pre>

== Hinweise zur Nutzung ==

Bei der Nutzung des ETL Managers sollten folgende Punkte beachtet werden:

* Ein laufender Prozess sollte nicht unnötig mehrfach parallel gestartet werden.
* Nach einem Lauf kann die Modulübersicht über „Aktualisieren“ neu geladen werden.
* Die Prozentanzeige ist kein Zeitindikator, sondern beschreibt den Fortschritt der Prozessschritte.
* Bei Fehlern sollte zuerst der Status und anschließend die Log-Ausgabe geprüft werden.
* Für tiefergehende Fehleranalysen sollten Administratorinnen und Administratoren oder technische Ansprechpartner einbezogen werden.
* Bei neuen verfügbaren Modulversionen sollte geprüft werden, ob ein Upgrade auszuführen ist.

== Details-Bereich ==

Über den Button „Details“ können zusätzliche technische Informationen zu einem Modul angezeigt werden.

Der Details-Bereich ist vor allem für fortgeschrittene Benutzerinnen und Benutzer, Administratorinnen und Administratoren oder den Support gedacht. Er kann unter anderem folgende Informationen enthalten:

* technische Modulkennung
* Systeminfo-ID
* technische Jobnamen
* verfügbare Jobs
* Rohdaten der Schnittstelle
* zusätzliche technische Moduldetails

Für den normalen Betrieb ist der Details-Bereich meist nicht erforderlich. Er ist vor allem dann hilfreich, wenn bei Rückfragen oder Supportfällen genaue technische Informationen benötigt werden.

== Diagnose-Bereich ==

Der Diagnose-Bereich ist eine technische Hilfsfunktion zur Prüfung der ETL-Manager-Installation. Er ist global angeordnet und nicht auf ein einzelnes Modul beschränkt.

Die Diagnose führt keine Reparaturen automatisch aus. Sie zeigt technische Informationen, mögliche Auffälligkeiten und Hinweise an. Zusätzlich können SQL- oder Shell-Hinweise angezeigt werden, die bei Bedarf von Administratorinnen und Administratoren kopiert und manuell ausgeführt werden können.

Der Diagnose-Bereich kann unter anderem folgende Informationen enthalten:

* Erreichbarkeit der REST-Schnittstellen
* Webapp-, Tomcat- und Java-Informationen
* Pfade und Dateisysteminformationen
* Festplattenspeicher
* Datenbankinformationen
* Prüfung der Log-Tabelle
* Versionsquellen
* bekannte Fehlerbilder
* kopierbare SQL- und Shell-Hinweise

Der Diagnose-Bereich ist vor allem für Administratorinnen und Administratoren oder technische Ansprechpartner gedacht. Für normale Anwenderinnen und Anwender ist er in der Regel nur dann relevant, wenn ein Fehler auftritt oder technische Informationen weitergegeben werden sollen.

== Administratorhinweise ==

Dieser Abschnitt enthält ergänzende technische Hinweise. Er richtet sich vor allem an Administratorinnen und Administratoren sowie an den technischen Support.

=== Herkunft der Versionsinformationen ===

Die Oberfläche zeigt eine installierte und eine verfügbare Version an.

Die installierte Version beschreibt den Stand, der in der Datenbank installiert ist. Falls die REST-Schnittstelle keinen Wert liefert, kann die Version aus der Tabelle <code>db_version</code> gelesen werden.

Die verfügbare Version beschreibt den ausgelieferten Stand im Dateisystem. Sie kann aus der Modul-XML-Datei gelesen werden. Für normale Module liegt diese Datei typischerweise unter:

<pre>
WEB-INF/conf/edustore/db/module/<modul>/conf/<modul>.xml
</pre>

Für das Kernmodul gilt ein Sonderfall. Die Modul-XML liegt unter:

<pre>
WEB-INF/conf/edustore/db/install/conf/kern.xml
</pre>

Zusätzlich kann eine Datei <code>VERSION</code> im jeweiligen Modulverzeichnis als Fallback verwendet werden.

=== Log-Tabelle ===

Die Log-Ausgabe des ETL Managers verwendet eine Datenbanktabelle für die Joblogs. Wenn diese Tabelle fehlt oder unvollständig ist, kann die Log-Ausgabe fehlschlagen.

Eine mögliche Struktur der Tabelle ist:

<pre>
CREATE TABLE IF NOT EXISTS job_log
(
job_instance_id bigint NOT NULL,
log text,
status text
);

CREATE UNIQUE INDEX IF NOT EXISTS ix_job_log1
ON public.job_log USING btree (job_instance_id);
</pre>

Diese SQL-Anweisungen sollten nicht automatisch durch die Oberfläche ausgeführt werden. Sie dienen als Hinweis für Administratorinnen und Administratoren und müssen bei Bedarf manuell geprüft und ausgeführt werden.

=== Typische technische Fehlerbilder ===

{| class="wikitable"
! Fehlerbild
! Mögliche Ursache
|-
| <code>/jobLog/{id}</code> liefert HTTP 500
| Die Tabelle <code>job_log</code> fehlt, ist unvollständig oder der Logeintrag ist noch nicht verfügbar.
|-
| <code>/job/list/{modul}</code> liefert HTTP 500
| Moduldateien fehlen, Pfade stimmen nicht oder die Webapp verwendet nicht den erwarteten Dateistand.
|-
| REST-Endpunkt liefert HTTP 404
| Der Context-Pfad, die Webapp, der Port oder ein Tunnel zeigt möglicherweise nicht auf die erwartete Anwendung.
|-
| Log erscheint erst nach erneutem Laden
| Der ETL-Lauf ist abgeschlossen, aber der Logeintrag war beim ersten Abruf noch nicht vollständig verfügbar.
|}

== Zusammenfassung ==

Der SuperX ETL Manager stellt eine zentrale Oberfläche zur Ausführung und Überwachung von ETL-Prozessen bereit. Für den täglichen Betrieb stehen vor allem die Aktionen „Unload“, „Update“, „Unload & Update“ und „Upgrade“ im Vordergrund.

Die Modulübersicht zeigt den Installationsstatus, Versionsinformationen, Datenquellen und Datenbankverbindungen. Der Bereich „Aktueller Lauf“ informiert über den Fortschritt eines gestarteten Prozesses. Die Log-Ausgabe liefert technische Zusatzinformationen und kann bei der Fehleranalyse helfen.

Details und Diagnose ergänzen die Oberfläche um technische Informationen für Support- und Administrationsfälle. Sie unterstützen bei der Analyse, führen aber keine automatischen Reparaturen aus.

= Installation und Verwaltung in der Shell mit Skripten =

== Installation von Modulen ==
Das Kernmodul enthält außer Administrationsabfragen und Tabellen keinerlei Inhalte. Die Inhalte werden in Form von Modulen hinzugefügt. Dazu gibt es vorgefertigte [[Kernmodul_Shellscripte#Modulverwaltung|Installationsscripte]].

=== Architektur von SuperX-Modulen ===
Die folgende Abbildung zeigt die Architektur von Modulen ab Beispiel vom HISCOB-Modul:

{| class="wikitable"
|-
!
!
|-
| Ein Modul besteht auf Datenbankseite aus Abfragen, Hilfstabellen, Datentabellen und Schlüsseltabellen (sowie Prozeduren).
Auf Webserver-Seite können auch XSL-Stylesheets vorhanden sein.
| [[Bild:modularchitektur_cob.png|417x307px]]
|}
Die Abbildung zeigt, dass ein Modul eigene Komponenten nutzt, aber auch auf Teile des Kernmoduls zugreift, z.B. das Orgranigramm - dies macht SuperX zu einem integrierten System. Neben dem Organigramm sind alle anderen Komponenten des Kernmoduls natürlich betroffen, z.B. Themenbaum, Userrechte.
Die Ordnerstruktur eines Moduls spiegelt die Komponenten des Systems wieder. Es gibt je ein Verzeichnis für datentabellen, schluesseltabellen und hilfstabellen.
Die Installation eines Moduls ist in der Dokumentation des jeweiligen Moduls näher beschrieben. Module, die auf dem Kernmodul 2.1 oder höher basieren, haben einen einheitlichen Aufbau.

=== Modulscripte im Kernmodul ===
Seit Version 2.1 werden die Datenbankschemata und Scripte der Module in einem einheitlichen Format zusammengestellt und in einer Datei $SUPERX_DIR/db/module/$MODULNAME/conf/$MODULNAME.xml gespeichert. Das XML-Format hat den Vorteil, dass die Scripte dynamisch für Postgres und Informix erzeugt werden können, und dass die Scripte vereinheitlicht werden. Aus dieser Datei werden die Scripte erzeugt, die das Modul jeweils für Postgres und Informix installieren / updaten /aktualisieren / überprüfen und entfernen. Die folgende Abbildung zeigt das Vorgehen:

{| class="wikitable"
|-
!
!
|-
| Aus der xml-Datei werden die jeweiligen Scripte für die Installation, den Update, die Extraktions-, Transformations- und Ladescripte (ETL) und die Deinstallation erzeugt.
| [[Bild:modulscripte_erzeugen.png|417x371px]]
|}

Die Modul-Scripte liegen als Shellscripte im Verzeichnis $SUPERX_DIR/db/bin, und sind an [[Kernmodul_Shellscripte#Modulverwaltung|anderer Stelle]] im Detail erläutert.

{| class="wikitable"
|-
!
!
|-
| module_install.x -name- -pfad-
z.B.:
module_install.x sos $SOS_PFAD
| Installiert ein Modul, d.h. erzeugt die Tabellen, Views, Funktionen und Abfragen. Die Abfragen werden in den Themenbaum eingehängt.
|-
| module_etl.x -name- -pfad-
z.B.:
module_etl.x sos $SOS_PFAD
| Aktualisiert das Modul, d.h. lädt die Rohdaten, Transformiert sie, und aggregiert die Hilfstabellen. Fehler werden in eine Log-Datei geschrieben, diese kann dann per Mail an einen Admin versandt werden. Wenn das Script erfolgreich durchläuft, wird die Tabelle systeminfo aktualisiert. 
Das Script wird nicht direkt als Cronjob aufgerufen, sondern von einem Shellscript, das die Umgebungsvariablen und Parameter setzt, z.B. cob_update.x.
|-
| module_drop.x -name- -pfad-
z.B.:
module_ drop.x sos $SOS_PFAD
| Entfernt das Modul bzw. die Tabellen, Views, Funktionen und Abfragen.
|-
| module_scripts_create.x -name- -pfad- -Datenbanksystem(optional, INFORMIX, POSTGRES)- -Versionsnr.-
| Erzeugt via XSL-Transformation die jeweiligen Scripte, die in den obigen Scripten aufgerufen werden, z.B. bau_install_ids.sql für das Installationsscript des Baumoduls beim Informix Dynamic Server.
|}

Neben den operativen Scripten erzeugt module_scripts_create.x auch html-Dateien zur Dokumentation eines Moduls in
$SUPERX_DIR/db/module/-Modulname-/conf/-Modulname-.html
(auch als rtf-Datei zu Einbindung in Modul-Dokumentationen) sowie zur Schnittstelle in
$SUPERX_DIR/db/module/-Modulname-/rohdaten/-Modulname-_unload.html
Darüber hinaus werden auch DBForms-Formulare erzeugt.

=== Installation eines Moduls: Allgemeines Vorgehen ===
Das Vorgehen bei der Installation eines Moduls ist standardisiert. Im folgenden eine Kurzbeschreibung, weiter unten finden Sie das Vorgehen am Beispiel des ZUL-Moduls im Detail.
* Entpacken Sie das Modul in $SUPERX_DIR
* Erweiterung der Umgebung in der Datei $SUPERX_DIR/db/bin/SQL_ENV: fügen Sie den Inhalt der jew. Beispieldatei SQL_ENV_-Modulname-.sam in der SQL_ENV an, wenn noch nicht vorhanden, und ändern Sie ggf. Email-Adressen für log- und Fehlermails.
* Entladen der Rohdaten; auch hier müssen vorher Umgebungsvariablen zum Vorsystem angepasst werden 
(Datei $-Modulname-_LOAD_PFAD/-Modulname-_ENV), hier liegt ebenfalls eine *.sam-Datei vor
* Kopieren der Rohdaten nach -Modulpfad-/rohdaten. Neuere SuperX-Module haben dafür vorgefertigte Scripte mit dem Namen -Modulname-_copy.x (z.B. zul_copy.x)
* Installieren Sie das Modul mit -Modulname-_erzeugen.x, z.B. mit zul_modul_erzeugen.x
* Wenn die Installation erfolgreich war, können Sie das Modul aktualisieren mit 
-Modulname-_update.x (ggf. mit Parametern) 
z.B. mit
zul__update.x
d.h. die ETL-Prozesse werden gestartet (s.u.).
* Wenn das Modul erfolgreich aktualisiert ist, wird eine Prüfprozedur gestartet, die die Daten plausibilisiert. Fehler und Warnungen finden Sie in der Datei $-Modulname-_ERRORDAT.
* Starten Sie Tomcat neu. Wenn Tomcat auf einem separaten Server installiert ist, müssen Sie vorher die Datei $SUPERX_DIR/webserver/tomcat/webapps/superx/WEB-INF/dbforms-config.xml dorthin übertragen.
* Schritt 7 wird bei jedem SuperX-Update wiederholt. Nun muss der Entladerhythmus geplant werden, und die Cronjobs werden eingerichtet. Es gibt eine Musterdatei $SUPERX_DIR/db/module/-MODULNAME-/-MODUL-_update_cron.x.sam , benennen sie diese um nach -MODUL-_update_cron.x und fügen Sie das Script in die crontab ein.

==== Allgemeines zum Laden ====
Zunächst müssen die Rohdaten aus dem Vorsystem entladen werden.
Für das Entladen gibt es ferner zwei Modi: Das "Pull"-Verfahren und das "Push"-Verfahren.
* Beim '''"Pull"-'''Verfahren wird einer Benutzerkennung auf dem SuperX-Rechner Zugriffsrecht auf die SOSPOS-Datenbank gegeben, und die Daten werden via TCP/IP aus dem Basissystem entladen. Bei APP / HISinOne als Quellsystem ist "Pull" das Standardvorgehen.
* Beim '''"Push"-'''Verfahren werden die Entladescripte auf den SOSPOS-Rechner kopiert und dort von einer Benutzerkennung auf dem SOSPOS-Rechner ausgeführt. Die Rohdaten müssen dann auf den SuperX-Rechner kopiert werden. Dieses Verfahren klappt bei Informix unter Unix problemlos, bei Entladen aus Postgres müsste das komplette SuperX-Kernmodul installiert werden.
Am einfachsten ist immer das "Pull"-Verfahren, das mit fast allen Quellsystemen funktioniert und wenig Konfiguration auf dem Quellsystem erfordert. Aufgrund von Sicherheitsvorkehrungen oder Netz-Infrastrukturen wählen aber viele Hochschulen das "Push"-Verfahren. Da derzeit Informix /Unix die gängigste Plattform an Hochschulen ist, ist dies auch kein Problem.

==== Einrichtung der Entladescripte ====
Im Push-Verfahren btw. unter SuperX können Sie mitgelieferte Shellscripte nutzen. Das folgende Beispiel des ZUL-Moduls zeigt das Vorgehen:
Die Entladescripte liegen im Verzeichnis $SUPERX_DIR/db/module/zul/rohdaten und lauten je nach Systemversion:
zul_unload.x

Die Scripte laufen nur, wenn die entsprechenden Umgebungsvariablen in der Datei ZUL_ENV (im gleichen Verzeichnis, ein Muster liegt vor in ZUL_ENV.sam) korrekt gesetzt sind, benennen Sie die Musterdatei um nach ZUL_ENV und tragen die richtigen Umgebungsvariablen ein, z.B. den Pfad für $INFORMIXDIR.
'''ZUL_ENV Die Umgebung für Entladescripte aus ZUL-GX(Auszug)'''
##Pfad für Entladedaten:
ZUL_PFAD=.; export ZUL_PFAD
##hier muss Unterverzeichnis unl existieren!

In der ZUL_ENV müssen außerdem folgende Umgebungsvariablen gesetzt werden (defaults sind bereits vorbelegt, aber hier und da müssen Sie sicher ran):
{| class="wikitable"
|-
! Variable
! Erläuterung
|-
|
| '''Nur für Informix gelten:'''
|-
| INFORMIXDIR
| Home-Verzeichnis von Informix
|-
| INFORMIXSERVER
| Name des Informixservers
|-
| ONCONFIG
| Name der onconfig, wenn auf dem SOS-Rechner mehrere Informix-Instanzen laufen
|-
| CLIENT_LOCALE
| Sprachumgebung (wichtig fürs Entladen von Datumsformaten)
|-
| SERVER_LOCALE
| dito
|}

{| class="wikitable"
|-
! Variable
! Erläuterung
|-
|
| '''Nur für Postgres gelten:'''
|-
| PGDATESTYLE
| Datumsformat "German"
|-
| PGPORT
| Port vom Postgres-Server, standardmäßig 5432
|-
| PGHOST
| Hostname oder IP-Adresse vom Postgres-Server
|-
| PGUSER
| Benutzerkennung für Postgres-Server (nur Datenbank, nicht Betriebssystem)
|-
| PGPATH
| Installationsverzeichnis von Postgres, z.B. /usr/local/pgsql
|-
| DB_PROPERTIES
| Pfad zur db-zul.properties-Datei mit den Zugangsparametern für SOSPOS unter Postgres
|-
| LOGGING_PROPERTIES
| Pfad zur Steuerungsdatei mit den Parametern für das Logging beim Entladen, voreingestellt auf ./logging.properties. Normalerweise brauchen Sie hier nichts ändern, wenn beim Entladen Probleme auftauchen, kann man den Level von SEVERE auf INFO oder FINEST ändern, dann werden die konkreten SQLs geloggt. Aber Achtung: wenn keine Fehler mehr auftreten, müssen Sie den Level wieder auf SERVERE ändern, sonst kommen Schlüsselworte in die Logdatei zul_unload.err, die dann bei der Übernahme nach SuperX fälschlicherweise zu Fehlermeldungen führen.
|}
Unter Postgres muss für das "Pull"-Verfahren beim Entladen die Datenbankverbindung in der Datei db-zul.properties eingetragen werden (Muster für Postgres liegt bei in db-zul_pg.properties). Dazu laden Sie einmal die Datei ZUL_ENV mit den obigen Parameter, starten den SuperX-Propadmin (siehe Administrationshandbuch Kernmodul) und richten die Verbindung zum SOSPOS-Server ein. Das Kennwort wird verschlüsselt gespeichert. Danach sind die Entladescripte für Postgres ausführbar.
Hinweis: Anders als Informix hat Postgres hat eine eigene, vom Basissystem unabhängige Benutzerverwaltung. Daher brauchen Sie den User, den Sie zum Entladen aus Postgres nutzen, nicht auf dem SuperX- oder SOSPOS-Rechner auf Betriebssystem-Ebene einrichten. Sie können also z.B. auf dem SuperX-Rechner zum Entladen aus SOSPOS die Kennung sospos des Postgres- Rechners verwenden. Oder Sie richten in der SOSPOS -Datenbank den Benutzer SuperX ein und geben ihm Leserecht auf die Tabellen sowie das Recht, Tabellen und Stored Procedures anzulegen.

{| class="wikitable"
|-
! Variable
! Erläuterung
|-
|
| '''Für alle Platformen gelten folgende Variablen:'''
|-
| ERRORMAIL
| An wen solle eine Logmail verschickt werden, wenn das Entladen nicht geklappt hat? (nur Unix).
|-
| LOGMAIL
| An wen soll immer eine Logmail verschickt werden
|-
| MAILPROG
| Pfad zum ausführbaren Mailprogramm unter Unix, Vorbelegung ist "mail", manche Unixe haben aber auch "mutt" oder "mailx".
|-
|
| Wenn die Rohdaten beim Push-Verfahren nach dem Entladen vom ZUL-Rechner auf den SuperX-Rechner kopiert werden sollen, dann werden für das Script zul_copy.x folgende Umgebungsvariablen benötigt:
|-
| COPY_METHOD
| Programm, das die Dateien kopiert; rsync und scp sind wählbar.
|-
| REMOTE_DIR
| Verzeichnis, in das die Rohdaten auf dem SuperX-Rechner kopiert werden sollen, in der Regel ist dies "/home/superx/db/module/zul/rohdaten"
|-
| REMOTE_USER
| Der Unix-Username auf dem SuperX-Rechner, in der Regel "superx".
|-
| REMOTE_HOST
| Der Rechnername bzw. die IP-Nr. des SuperX-Rechners.
|}
Dann starten Sie das Script zul_unload.x. Wenn es gelaufen ist, müssten die Dateien im unl-Verzeichnis stehen. Prüfen Sie dann bitte, ob dort Dateien mit 0 bytes stehen. Die Logdatei heisst zul_unload.err.

===== Entladen unter Windows =====
Für das Entladen unter Windows gibt es Muster-Dateien im jew. Rohdaten-Verzeichnis, z.B. $SOS_PFAD/rohdaten/sos_unload.bat. Die Einrichtung geschieht dann in [[Kernmodul_Komponentenverwaltung#Java-Client_zum_Entladen_von_Quell-Datenbanken|Java]]. Ans Ende der Datei können Sie noch schreiben:
date /T >superx.datum
Dann wird auch die Datumsdatei geschrieben.

===== Dateitransfer beim Push-Verfahren =====
Wenn Sie das Verzeichnis nicht gemounted haben, müssen das Verzeichnis unl, die zul_unload.err und die superx.datum dann in das Verzeichnis $ZUL_LOAD_PFAD auf dem SuperX-Rechner kopiert werden, ein Script dafür liegt ebenfalls bei (zul_copy.x). Das Entladedatum wird danach in der Textdatei $ZUL_LOAD_PFAD/superx.datum gespeichert; wenn das Script einen Fehler findet, dann wird das vorherige Datum (in der Datei superx.datum.alt) gesetzt.

Für den Transfer der Rohdaten beim Push-Verfahren wird in SuperX die dateibasierte Schnittstelle genutzt. Unter UNIX läßt sich dieser Transfer vollends automatisieren, indem die Programme scp oder rsync auf der Basis des OpenSSH-Pakets genutzt werden. Beide setzen auf das ssh-Protokoll 2 auf und stellen somit einen verschlüsselten Dateitransfer sicher. Auch [[Kernmodul_Komponentenverwaltung#Einrichtung_von_SFTP|sftp]] ist möglich.
In den jeweiligen Modulen wird im Verzeichnis rohdaten eine Beispieldatei mit dem Namen -MODULNAME-_ENV.sam ausgeliefert, die Sie umbenennen können nach -MODULNAME-_ENV. Darin werden am Ende der Datei die Parameter zum Kopieren festgelegt, also die Userkennung REMOTE_USER, der Hostname REMOTE_HOST, und die Methode des Kopierens (COPY_METHOD) sowie die jeweiligen Zielpfade. Diese Umgebungsvariablen werden von dem jeweiligen Script -modulname-_copy.x benutzt.

===== Entfernen der Passworteingabe unter Unix =====
Damit die Passworteingabe unter Unix entfällt, muss man wie folgt vorgehen:
Loggen Sie sich zunächst testweise einmal ein. Wenn Sie z.B. vom COB-Server auf den SuperX-Server kopieren wollen, loggen Sie sich als user cob auf cobhost ein mit 
ssh superx@superxhost
Beim ersten Mal müssen Sie die Sicherheitsabfrage mit "yes" bestätigen.
Erzeugen Sie auf dem Quellrechner einen öffentlichen Schlüssel mittels

ssh-keygen -t ed25519 -C "cob@cobhost"

wobei man eine leere Passphrase vergibt. Der öffentliche Teil dieses Schlüssels (~/.ssh/id_ed25519.pub) muss auf dem Zielrechner in die Datei ~/.ssh/authorized_keys eingefügt werden, ggf. muss die Datei neu erzeugt werden.
Wenn z.B. auf dem COB-Server unter der Kennung cob ein Key wie folgt erzeugt wurde:

;Beispieleintrag eines Public Keys:

ssh-ed25519 AAAAC3N.[hier viele kryptische Zeichen]....4V cob@cobhost

Dann wird genau diese Zeile in der Datei /home/superx/.ssh/authorized_keys angefügt (die Datei kann mehrere PublicKeys enthalten, ein Eintrag pro Absatz).
Achten Sie auch auf Dateirechte: Die Verzeichnisse und Dateien sollten keine Schreibrechte für Gruppen haben. Im Zweifelsfall z.B. für den user superx:
chmod 700 /home/superx/.ssh
chmod 700 /home/superx/.ssh
chmod 600 /home/superx/.ssh/authorized_keys
Danach sollte z.B. der Login vom cobhost als user cob mit ssh superx@superxhost ohne Passworteingabe klappen. Wenn nicht, schalten Sie das Logging mit ssh -v superx@superxhost ein. Eine Möglichkeit ist, dass die PublicKey-Authentifizierung in der Konfigurationsdatei des SSHD (normal /etc/ssh/ssh_config) abgeschaltet ist. Weitere Diagnosen liefert die Datei /var/log/messages.
Sie können außerdem noch einschränken, von welchem Host die obige Authentifizierung ermöglicht wird. Dazu setzen Sie den Parameter "from=*.uni-xy.de" davor, z.B.

{| class="wikitable"
|-
!
!
|-
| Einschränkung "from" 
in authorized_keys
| from="*.uni-xy.de" ssh-rsa AAAAB3Nza…[hier viele kryptische
Zeichen]…pg6VkCc= cob@cobhost
|}

Wenn Sie die Kopiermethode scp benutzen, und die obige "authorized_keys"-Metohde mit PublicKey nicht nutzen wollen, können Sie auch mit Private Keys arbeiten (siehe SSH-Doku). Dazu können sie in der *_ENV-Datei in dem Parameter SCP_OPTS den Verweis auf den private Key setzen.
{| class="wikitable"
|-
!
!
|-
| SCP_OPTS in *_ENV: 
Beispiel COB_ENV
| SCP_OPTS="-p -B -i /home/cob/.ssh/superx_key"
export SCP_OPTS
|}

===== Entfernen der Passworteingabe unter Windows =====
Wenn Sie die ssh-Shell putty aus dem Installationspaket nutzen, haben Sie im Installationsordner auch die Anwendung "puttyGen.exe". Wenn Sie putty als reine Executable nutzen, laden Sie die Anwendung separat herunter. [http://winscp.net/download/puttygen.exe PuttyGen]
* Folgen Sie der Anleitung auf der Seite http://winscp.net/eng/docs/ui_puttygen, um den SSH2-DSA oder RSA Schlüssel zu erzeugen. Für den Schlüssel bitte kein Passwort vergeben, wenn Sie das Tool automatisiert nutzen.
* Den privaten Schlüssel geben Sie in Putty bzw. Winscp im Menü "Session" im Feld "Private Key File" an.
* Der Button "Save public key" ist nicht für OPENSSH unter Linux als Zielserver geeignet. Im folgenden Screenshot sehen Sie den markierten Bereich, den Sie kopieren müssen:
[[Bild:puttygen.png|413x402px]]
* Kopieren Sie Ihren Public Key, den Sie oben mit PuttyGen erzeugt haben, zur Datei "authorized_keys" und kopieren Sie diese in das Verzeichnis ~/.ssh/
* Im Profil unter Connection -> SSH -> Auth -> Credentials geben Sie den Pfad zum privaten Schlüssel in "Private key file" an.
* Bei erneutem Login mit Putty oder Winscp sollte die Passwortabfrage entfallen.

===== Einrichtung von SFTP (Server) =====
Beim Push-Verfahren wird, wenn mit scp oder rsync kopiert wird, eine Login-Shell vorausgesetzt. Wenn dies aus Sicherheitsgründen nicht gewünscht ist bzw. wg. Einsatz von Windows nicht möglich ist, können Sie auch sftp nutzen, dies wird in modernen ssh-Servern mitgeliefert und bietet ebenfalls verschlüsselten Datentransfer. Zur Einrichtung des Servers:
Der SSH-Dienst wird wie folgt konfiguriert (am Beispiel Ubuntu Linux 22.04 LTS) mit dem SFTP-Verzeichnis /home/sftp/-benutzername:

In der Datei /etc/ssh/sshd_config die Zeile auskommentieren:
#Subsystem sftp /usr/lib/openssh/sftp-server
und stattdessen:
Subsystem sftp internal-sftp
Match Group sftponly
ChrootDirectory /home/sftp/%u
ForceCommand internal-sftp
AllowTcpForwarding no

Danach starten Sie den SSH-Dienst neu:
service ssh restart

Dann legen Sie die Gruppe "sftponly" an:
groupadd sftponly
und dann den Unix-User an, und geben ihm die Gruppe "sftponly". Hier ein Script:
#!/bin/sh
SFTPUSERNAME=$1
mkdir -p /home/sftp/$SFTPUSERNAME
useradd -b /home/sftp -s /bin/false -G sftponly $SFTPUSERNAME
chown root:root /home/sftp/$SFTPUSERNAME
chmod 755 /home/sftp/$SFTPUSERNAME
mkdir -p /home/sftp/$SFTPUSERNAME/incoming
chown $SFTPUSERNAME:sftponly /home/sftp/$SFTPUSERNAME/incoming

Danach legen Sie mit
passwd $SFTPUSERNAME
ein Passwort fest.

Der User kann sich dann nicht mehr mit ssh einloggen, nur noch mit sftp, und landet beim Login in /home/$KENNUNG, in einem "chroot-Käfig", und der User kann mit SFTP in den Ordner "incoming" schreiben. Zum Testen geben Sie ein:
sftp $KENNUNG@-Host-

Wenn beim SFTP Login die Meldung kommt:
client_loop: send disconnect: Broken pipe
müssen Sie darauf achten dass das Home-Verzeichnis des Users nicht dem User gehört, sondern root.

Wenn der Login klappt, können Sie nach dem [[Kernmodul_Komponentenverwaltung#Entfernen_der_Passworteingabe_unter_Unix|oben]] beschriebenen Verfahren die Passworteingabe durch PublicKey-Authentifizierung ersetzen.

===== Einrichtung von SFTP =====
Für das Kopieren der Rohdaten können Sie im Kopierscript "-modulname-_copy.x" auch sftp-Kommandos nutzen. Sie müssen nur in der ENV-Datei die Variable
COPY_METHOD=sftp
setzen. Alle anderen Variablen und Mechanismen wie z.B. [[Kernmodul_Komponentenverwaltung#Entfernen_der_Passworteingabe_unter_Unix|Entfernen der Passworteingabe]] entsprechen denen von SCP / SSH (s.o.).
Spezielle Optionen fürs sftp können Sie in der Umgebungsvariable SFTP_OPTS setzen. Es kann z.B. sein, dass das Kopieren großer Dateien in einen Timeout läuft. Bei CSV bietet es sich an, die Dateien zu komprimieren, sie können also setzen:
SFTP_OPTS="-oCompression=yes"
export SFTP_OPTS
Danach wiederholen Sie das kenn_copy.x
Dies ist nur ein Beispiel. Weitere Optionen für SFTP entnehmen Sie der manpage.
Das Kopieren mit sftp klappt übrigens auch unter Windows z.B. mit dem Programm [http://winscp.net/eng/docs/lang:de winscp]. Dies wird im folgenden erläutert.

===== Einrichtung von SFTP unter Windows =====
Unter Windows ist das Standardprogramm für SFTP die Anwendung [http://winscp.net/eng/docs/lang:de winscp]. Sie können die Passworteingabe analog zu Putty [[Kernmodul_Komponentenverwaltung#Entfernen_der_Passworteingabe_unter_Windows|entfernen]]. Danach können Sie eine Session erzeugen:

[[Bild:winscp1.png|517x364px]]

Im Feld "Private key file" geben Sie den private key ein, den Sie [[Kernmodul_Komponentenverwaltung#Entfernen_der_Passworteingabe_unter_Windows|oben]] erzeugt haben. Klicken Sie dann auf "Save session", und geben Sie einen kurzen, sprechenden Namen ohne Leerzeichen oder Umlaute, z.B. "superx@vmmulti1"
Sie müssen nun die Verzeichnisse lokal und remote in der Winscp-Session speichern, im Menüpunkt "Directories":

[[Bild:winscp2.png|517x359px]]

Vergessen Sie auch hiernach nicht, die Session zu speichern.
Danach testen Sie einmal den Zugang. Wenn das klappt können Sie Winscp auch für die Kommandozeile automatisieren. Sie erzeugen zunächst eine Textdatei mit den Kommandos für Winscp, dies enthält auch die zu übertragenden Dateien. Der Aufbau der Datei ist wie folgt:
open -Sessionname-
# Upload the file to current working directory
put -Datei-
# Disconnect
close
# Exit WinSCP
exit

Die zu übertragenden Dateien sind in der Musterdatei des jew. Moduls in rohdaten/-Modulname-_sftp.txt aufgelistet, Sie müssen lediglich
* den "/" durch einen "\" ersetzen
* das Entladeprotokoll -Modulname-_unload.err und die Datumsdatei superx.datum hinzufügen
Hier ein Beispielscript fürs das Studierenden-Modul:
open superx@vmmulti1
# Change remote directory
# Upload the file to current working directory
put sos_unload.err
put superx.datum
put unl\konstanten.unl
put unl\sos_studenten.unl
put unl\sos_hzb.unl
put unl\sos_faecher.unl
put unl\sos_pord_to_stg.unl
put unl\sos_pruefungenext.unl
put unl\sos_pruefungen.unl
put unl\sos_lab_astat_attributes.unl
put unl\sos_stud_loe.unl
put unl\sos_faecher_ext.unl
put unl\sos_faecher_kontrolle.unl
put unl\sos_pruefungen_kontrolle.unl
put unl\sos_anschri.unl
put unl\sos_parstg.unl
put unl\sos_hsnr.unl
put unl\semester.unl
put unl\cif.unl
put unl\cifx.unl
put unl\k_pvers.unl
put unl\k_stg.unl
put unl\k_stgext.unl
put unl\k_abstgv.unl
put unl\sos_pord.unl
put unl\sos_dipl.unl
put unl\sos_minder.unl
put unl\sos_stud_d.unl
put unl\sos_pords.unl
put unl\sos_porg.unl
put unl\sos_labzuord.unl
put unl\sos_pnrzuord.unl
put unl\sos_gewichtungsvariante.unl
put unl\sos_gewichtungregel_filter.unl
put unl\sos_gewichtungregel.unl
put unl\personattribute.unl
put unl\personattributetype.unl
put unl\personattribute_value_list.unl
put unl\stu_update_prot.unl
put unl\exa_update_prot.unl
put unl\sos_accredited_ects.unl
put unl\sos_pord_orgeinheit.unl
# Disconnect
close
# Exit WinSCP
exit

Die Datei hat z.B. den Namen winscp_example_script.txt. Dann können Sie das Script aufrufen mit dem DOS-Kommando:
winscp /script=-Pfad zu-\winscp_example_script.txt

Hier ein Screenshot wie das dann aussieht:

[[Bild:winscp3.png|609x337px]]

Das DOS-Kommando läßt sich dann über die Windows-Taskverwaltung automatisieren.

===== Java-Client zum Entladen von Quell-Datenbanken =====
Zum Entladen aus dem operativen Vorsystem wird unter Informix dbaccess genutzt. Unter Postgres wird generell der SuperX-JAVA-Client zum Entladen genutzt, denn SuperX benötigt ein spezielles, an Informix angepasstes [[Kernmodul_Komponentenverwaltung#Format_der_Unload_Dateien_CSV|CSV-Format]], das sich mit Bordmitteln von Postgres (copy-Befehl) nicht erzeugen lässt. Es kann aber auch sinnvoll sein, aus der Informix-Datenbank mit SuperX-JAVA-Client zu entladen, z.B. wenn Sie kein UNIX-dbaccess auf dem Vorsystem installiert haben.

Wenn Sie das jew. operative Vorsystem im PUSH-Verfahren entladen wollen, d.h. die Rohdaten werden auf dem Vorsystem entladen und auf den SuperX-Rechner kopiert, dann müssen Sie spezielle Vorkehrungen treffen. SuperX nutzt generell zum Entladen eigene Java-Klassen. Beim Entladen im PULL-Verfahren sind diese Klassen vorhanden, denn die Entladeroutine läuft auf dem SuperX Rechner. Wenn Sie aber PUSH nutzen wollen, werden die SuperX-Java-Klassen auf dem Liefersystem benötigt, und die Entladeroutine muss konfiguriert sein. Im Folgenden nutzen wir das Beispiel "Entladen im Push-Verfahren aus SVA-GX unter Postgres". Gehen Sie dazu wie folgt vor:
* Kopieren Sie die Dateien
** superx*jar
** postgresql-*.jar
** jfor-0.7.2rc1.jar
* vom SuperX-Rechner im Verzeichnis $SUPERX_DIR/tomcat/webapps/superx/WEB-INF/lib auf den Quellrechner in ein Unterverzeichnis lib unter rohdaten (z.B. /home/sva/superx/rohdaten/lib). In rohdaten liegt die bisherige Entladeroutine (z.B. sva_unload.x).
* Kopieren Sie die *_ENV.sam -Datei nach *_ENV, also hier SVA_ENV.sam nach SVA_ENV
* Fügen Sie dann folgenden Passus in die Umgebungs-Datei der Entladeroutine, hier also SVA_ENV:
#Pfad zu den SuperX-Java-Libraries
#Der JDBC_CLASSPATH enthält alles, was der jdbc-Client in superx für den Datenbankzugriff braucht.
#jfor*.jar, postgresql*.jar
JDBC_CLASSPATH="$SVA_LOAD_PFAD/lib/superx5.0.jar:$SVA_LOAD_PFAD/lib/postgresql-42.2.19.jar:$SVA_LOAD_PFAD/lib/jfor-0.7.2rc1.jar"
export JDBC_CLASSPATH

Wenn dann noch die Variablen [[Kern_Installation_Upgrade#Anpassen_der_Datenbankparameter_db.properties|DB_PROPERTIES]] und LOGGER_PROPERTIES korrekt gesetzt sind, kann die Entladeroutine bei SX_CLIENT=jdbc (Wenn Sie unter Windows entladen, oder Informix ohne dbaccess entladen wollen) oder SX_CLIENT=psql (wenn Sie Postgres unter UNIX nutzen) mit Java entladen.

Danach können Sie das Entladescript ausführen:
sva_unload.x
Die Logdatei lautet sva_unload.err

Zum Kopieren der Rohdaten zum SuperX-Server passen Sie folgende Variablen an:

{| class="wikitable"
|-
! Variable
! Erläuterung
|-
|
| Wenn die Rohdaten beim Push-Verfahren nach dem Entladen vom SVA-Rechner auf den BI-Rechner kopiert werden sollen, dann werden für das Script sva_copy.x folgende Umgebungsvariablen benötigt:
|-
| COPY_METHOD
| Programm, das die Dateien kopiert; rsync, [[Kernmodul_Komponentenverwaltung#Einrichtung_von_SFTP|sftp]] und scp sind wählbar [Achtung: diese müssen dann betriebssystemseitig installiert sein].
|-
| REMOTE_DIR
| Verzeichnis, in das die Rohdaten auf dem BI-Rechner kopiert werden sollen, in der Regel ist dies "/home/superx/db/module/sva/rohdaten"
|-
| REMOTE_USER
| Der Unix-Username auf dem BI-Rechner, in der Regel "tomcat" oder "superx".
|-
| REMOTE_HOST
| Der Rechnername bzw. die IP-Nr. des BI-Rechners.
|}
Danach starten Sie
sva_copy.x
Die Logdatei lautet sva_copy.err

Weitere Entladeparameter werden in den modulspezifischen Administrationshandbüchern beschrieben.
{{Hinweis|Bei neuen SuperX-Versionen reicht es in der Regel, die modulspez. Dateien auszutauschen, also hier sva_unload.* etc.}}

== Update eines Moduls: Allgemeines Vorgehen ==
Wenn das Entladen aus dem Vorsystem geklappt hat (sofern es ein Vorsystem gibt), können Sie die Daten laden. Zum Update bzw. zum Laden der Rohdaten gehen in das Verzeichnis $SUPERX_DIR/db/module/-Modulname- und führen das Script aus:
-Modulname-_update.x
Die Logdatei lautet L_-Modulname-_UPDATE.log, im Mandantenfähigen Betrieb "L_-Modulname-_UPDATE-MANDANTID-.log".
Für die Aufnahme der Laderoutine in die crontab gibt es im gleichen Verzeichnis Musterscripte nach dem Namensmuster:
-Modulname-_update_cron.x
Je nach Push/Pull-Szenario können Sie auch den Unload darin starten oder nicht.

=== Modulupdate in mandantenfähigen Installationen ===
Der Modulupdate in mandantenfähigen Installation findet in einer SuperX-Installation statt, allerdings werden die einzelnen Scripte mit unterschiedlichen Umgebungsvariablen, wie sie in SQL_ENV.-MANDANTID- definiert ist, z.B. SQL_ENV.FHRO.
In der SQL_ENV.-MANDANTID- werden unterschiedliche Pfade für den jeweiligen *_LOAD_PFAD gesetzt, wobei in der Regel die Mandandid ein Unterverzeichnis vom "normalen" LOAD_PFAD ist. So ist z.B. beim COB-Modul folgender Pfad anzusetzen:
Normale SuperX-Installation:
COB_LOAD_PFAD=$SUPERX_DIR/db/module/cob/rohdaten
Mandantenfähige SuperX-Installation:
COB_LOAD_PFAD=$SUPERX_DIR/db/module/cob/rohdaten/FHRO
Unterhalb von FHRO befindet sich noch einmal die Entladeroutine sowie das Unterverzeichnis unl mit den Rohdaten. Dieses Verzeichnis FHRO kann der Einfahheit halber auch ein symbolischer Link auf den gemounteten COB-Rechner sein.
Durch Setzen der Mandantennummer in der Umgebungsvariable MANDANTID in der jeweiligen SQL_ENV des Mandanten werden die ETL-Scripte anders ausgeführt: Die Logdateien werden jeweils mit der Mandantennummer versehen (z.B. L_cob_updateFHRO.log), damit die Übersicht nicht verloren geht und der gleichzeitige Update mehrerer Mandanten in eine rsuperX-Installation möglich ist.
Außerdem können weitreichende Steuerungsmechanismen im Modulupdate eingesetzt werden: Nach jedem ETL-Schritt können optional mandantenspezifische Scripte aufgerufen werden. Diese müssen folgende Namenskonvention einhalten:
-Scriptname-_-MANDANTID-.sql
Also für eine hochschulspezifische Transformation im COB-Modul des Mandanten FHRO wird eine Datei namens
cob_trans_FHRO.sql
mit entsprechenden SQL-Anweisungen angelegt.

=== Format der Unload Dateien CSV ===
Generell gilt das Prinzip, daß Daten vom Vorsystem in CSV entladen werden, und dann in sog. Ladetabellen hochgeladen werden. Da CSV je nach DBMS unterschiedlich implementiert wird, hier eine kurze Beschreibung des Formats, das im wesentlichen den Vorgaben von Informix LOAD entspricht:
* Zeichenformat: UNIX LATIN1 oder UTF-8
* Feldtrenner: ^
* Satztrenner: Feldtrenner + UNIX NEWLINE
* Zeilenschaltung: Umbrüche innerhalb von Textfeldern sind als \ + NEWLINE codiert
* Feldtrenner, die im Textfeld vorkommen, werden mit "\" maskiert. Ebenso das Zeichen "\" selbst
* Die Datumsformate sind bei Datumsfeldern immer im deutschen Format (DD.MM.YYYY) vorgesehen
* Boolean-Werte werden durch "true" oder "false" codiert
* Der Dezimaltrenner ist ".", kein 1000-er Punkt bei Zahlen.
* Leerstrings und Leerzeichen werden als " " (Leerzeichen) exportiert.

== Upgrade eines Moduls: Allgemeines Vorgehen ==
Zum Upgrade bzw. zum Zurücksetzen des Moduls auf den Auslieferungszustand entpacken Sie das Paket in $SUPERX_DIR und gehen in das Verzeichnis $SUPERX_DIR/db/module/-Modulname-/upgrade und führen das Script aus:
-Modulname-_upgrade.x
Ausnahme: beim Kernmodul gibt es i.d.R. ein spezielles [[Kern_Installation_Upgrade#Standardvorgehen_beim_Upgrade|Upgrade Script]].

Die Logdatei lautet upgrade.log, im Mandantenfähigen Betrieb "upgrade-MANDANTID-.log".

Wenn Sie einen separaten Tomcat-Rechner betreiben, müssen Sie das Paket dort ebenfalls entpacken, und vom Datenbankserver die Datei $SUPERX_DIR/webserver/tomcat/webapps/superx/WEB-INF/dbforms-config.xml an die gleiche Stelle auf den Tomcat Rechner kopieren. Ein nochmaliges Ausführen des Upgrade Scriptes ist nicht nötig, weil dies nur die Datenbank betrifft.

== Hochschulspezifische Anpassung eines Moduls ==
=== Dateibasierte hochschulspezifische Anpassung ===
Nach der Installation bzw. beim Upgrade können Sie hochschuleigene SQL Scripte ausführen lassen. Erzeugen Sie dazu eine Datei
$SUPERX_DIR/db/module/-Modulname-/conf/customize.sql
bei Mandantenbetrieb
$SUPERX_DIR/db/module/-Modulname-/conf/customize-MANDANTID-.sql
und füllen Sie diese mit einem beliebigen Inhalt. Das Script wird beim Upgrade des Moduls automatisch am Ende ausgeführt.
=== Datenbankbasierte hochschulspezifische Laderegeln ===
Eine Laderoutine gliedert sich in die Schritte
#Unload: Entladen der CSV Dateien aus dem jew. Vorsystem
#Load: Upload der CSV Dateien
#Trans: Transformation der Daten
#Aggr: Aggregation der Daten
#Test: Test der Daten
#System: Standdatum bei Erfolg aktualisieren
Es ist möglich über sog. "Preparation"- oder "Finalize"-[[Kernmodul_Shellscripte#Hochschulspezifische_Transformationen_im_ETL-Prozess|Scripte]] die Laderoutine am Ende von LOAD bzw. TRANS anzupassen. Dieses Verfahren ist weiterhin möglich, ist aber bzgl. Clustering und Schreibzugriff recht unflexibel.

Es ist auch möglich im Browser hochschulspezifische Scripte am Ende des jeweiligen Schrittes einer Laderoutine anzulegen. Dies funktioniert so: Die Laderoutine führt zunächst den allgemeinen, von uns vorgegebenen Ladeschritt aus. Wenn dann eine Repository-Variable mit einem gewissen Namensschema existiert, wird sie ausgeführt. Das Namensschema lautet
<source lang="xml">
<<Kürzel der Komponente>>_<<Ladeschritt>>_CUSTOM
</source>.
* Bei Hauptladeroutinen ist dies
*# Laden: '''Kürzel der Komponente'''_load_CUSTOM, z. B. sos_load_CUSTOM
*# Transformation: '''Kürzel der Komponente'''_trans_CUSTOM, z. B. sos_trans_CUSTOM
*# Aggregation: '''Kürzel der Komponente'''_aggr_CUSTOM, z. B. sos_aggr_CUSTOM
* Bei Unterladeroutinen ist dies '''Kürzel der Komponente'''_'''ID des Ladeschritts'''_CUSTOM, also z. B. cob_trans_fin_busa_CUSTOM für die Unterladeroutine "Lade Buchungen aus FIN"

Um eine Variable neu einzurichten:
* Gehen Sie in den BI-Standardberichten auf Administration/Hochschul-Repository.
* Wählen Sie das jeweilige Sachgebiet und schicken Sie das Formular ab.
* Klicken Sie bei einer Beispielzeile auf '''Bearbeiten'''.
* Im neuen Fenster klicken Sie oben ganz rechts auf das Symbol '''Datensatz kopieren'''.
* Definieren Sie die Variable z. B.
** als Variablenname die ID z. B.: fin_load_CUSTOM
** Art der Variable: ein für Sie sprechender Schlüssel mit Modulkürzel, z. B. "fin_Laderegel"
** als Inhalt der Variable die gewünschten Befehle, z. B.
<source lang="sql">
update fin_buch_neu set ch110_institut=buchungsab_fb where length(buchungsab_fb)=5;
</source>
** aktiv=1
** gültig seit 1.1.1900
** gültig bis 1.1.3000
* Klicken Sie oben rechts auf das Häkchen-Symbol für '''Datensatz einfügen'''.
* Schließen Sie das Fenster.

Analog können Sie auch die [[Kernmodul_Komponentenverwaltung#Dateibasierte_hochschulspezifische_Anpassung|customize]]-Regeln" ins Repository verlagern. Hier heißt die Variable z.B. fin_install_CUSTOM.

== Entfernen eines Moduls ==
Wenn Sie ein Modul nicht mehr benötigen, starten Sie das Script 
$SUPERX_DIR/db/module/-Modulname-/-Modulname-_modul_entfernen.x. 
Dieses Script löscht alle Tabellen, Prozeduren und Abfragen aus der Datenbank, und löscht auch die Einträge im Themenbaum. Danach können Sie den Pfad $SUPERX_DIR/db/module/-Modulname-löschen.
Wenn Sie nur die Inhalte der Daten- und Hilfstabellen des Moduls löschen wollen (z.B. aus Datenschutzgründen), ohne das ganze Modul zu deinstallieren, können Sie dies mit folgendem Befehl tun:
DOSQL $SUPERX_DIR/db/module/-Modulname-/-Modulname-_purge_pg.sql (für Postgres) 
bzw. 
DOSQL $SUPERX_DIR/db/module/-Modulname-/-Modulname-_purge_ids.sql (für Informix)

Kernmodul Komponentenverwaltung

2026-07-13T06:45:00Z

Andrek:

Die Komponentenverwaltung im Kernmodul kann je nach Aufgabe über die Browseroberfläche oder über Shell-Skripte erfolgen.

Bisher wurden die Installation, Deinstallation, Aktualisierung und das Upgrade von Modulen überwiegend über Skripte in der Shell durchgeführt. Ab Kernmodul 6.0 steht zusätzlich eine Komponentenverwaltung über die Browseroberfläche zur Verfügung. Diese Browseroberfläche wird im Folgenden als SuperX ETL Manager beschrieben.

Der SuperX ETL Manager ist vor allem für die Ausführung und Überwachung von ETL-Prozessen sowie für Modul-Upgrades vorgesehen. Die Installation und Deinstallation von Modulen stehen dort bisher nicht zur Verfügung und werden weiterhin über die Shell-Skripte durchgeführt.

Der folgende Artikel ist daher in zwei Bereiche gegliedert: Zuerst wird die Nutzung des SuperX ETL Managers beschrieben. Anschließend folgt die bisherige Dokumentation zur Installation und Verwaltung von Modulen mit Skripten.

= Komponentenverwaltung im Browser: SuperX ETL Manager =
Der SuperX ETL Manager dient dazu, ETL-Prozesse der installierten SuperX-Module über die Weboberfläche auszuführen und zu überwachen. Er bietet eine zentrale Übersicht über installierte Module, verfügbare Aktionen, Versionsinformationen, Datenquellen, den aktuellen Lauf sowie technische Zusatzinformationen für die Fehlersuche.

Der Schwerpunkt der Oberfläche liegt auf dem täglichen Betrieb: Anwenderinnen und Anwender können Laderoutinen starten, den aktuellen Stand eines Laufs verfolgen und bei Bedarf die Log-Ausgabe einsehen. Technische Detail- und Diagnoseinformationen stehen ebenfalls zur Verfügung, sind aber vor allem für Administratorinnen und Administratoren oder den Support gedacht.

[[Bild:SuperX_ETL_Manager_Uebersicht.png|Gesamtübersicht des SuperX ETL Managers mit Modulübersicht, Filterbereich, Aktionsbuttons und aktuellem Lauf.]]

== Aufbau der Oberfläche ==

Die Oberfläche besteht im Wesentlichen aus folgenden Bereichen:

* Filterbereich
* Modulübersicht
* Aktionsbuttons pro Modul
* Bereich „Aktueller Lauf“
* Log-Ausgabe
* Details-Bereich
* Diagnose-Bereich

Über den Filterbereich kann die angezeigte Modulliste eingeschränkt werden. Die Modulübersicht zeigt die wichtigsten Informationen zu den vorhandenen Modulen. Über die Aktionsbuttons können ETL-Prozesse gestartet werden. Der Bereich „Aktueller Lauf“ zeigt den zuletzt gestarteten oder aktuell laufenden Prozess an.

Die Bereiche „Details“ und „Diagnose“ liefern zusätzliche technische Informationen. Sie sind hilfreich für Supportfälle, aber für die normale Bedienung nicht zwingend erforderlich.

== Modulübersicht ==

Die Modulübersicht zeigt die installierten bzw. erkannten Module mit ihren wichtigsten Eigenschaften.

{| class="wikitable"
! Spalte
! Bedeutung
|-
| Modul
| Zeigt den Namen und das technische Kürzel des Moduls, zum Beispiel „Administration“ mit dem Kürzel „kern“ oder „Kennzahlen“ mit dem Kürzel „kenn“.
|-
| Status
| Zeigt, ob das Modul installiert ist.
|-
| Versionen
| Zeigt die installierte Version und die verfügbare Version des Moduls.
|-
| Letztes Update
| Zeigt den Zeitpunkt des letzten bekannten Updates.
|-
| Datenquelle
| Zeigt, aus welcher Datenquelle das Modul seine Daten bezieht oder auf welcher Datenbasis der ETL-Prozess arbeitet.
|-
| DB-Verbindung
| Zeigt, ob die Verbindung zur Datenbank bzw. Datenquelle aktuell erreichbar ist.
|-
| Aktionen
| Zeigt die verfügbaren Aktionen für das jeweilige Modul.
|}

=== Versionen ===

In der Spalte „Versionen“ werden zwei Werte angezeigt:

* installierte Version
* verfügbare Version

Die installierte Version beschreibt den Stand, der aktuell in der Datenbank installiert ist. Die verfügbare Version beschreibt den ausgelieferten Stand des Moduls, der in der Installation vorliegt.

Wenn die verfügbare Version höher ist als die installierte Version, sollte in der Regel ein Upgrade des Moduls durchgeführt werden. Dadurch werden die Datenstrukturen des Moduls auf den ausgelieferten Stand aktualisiert.

=== Datenquelle ===

Die Datenquelle gibt an, aus welchem System ein Modul seine Daten bezieht oder auf welcher Datenbasis es arbeitet.

SuperX ist ein Data Warehouse. Viele Module übernehmen Daten aus externen vorsystemen. Beispiele für solche Datenquellen sind:

* cob für Kostenrechnung
* mbs für Finanzrechnung, Inventar oder Gebäude/Räume/Flächen
* sva für Personal- und Stelleninformationen
* hisinone bei entsprechend angebundenen Modulen

Daneben gibt es Module, die auf bereits in SuperX vorhandene Daten zurückgreifen. In solchen Fällen wird als Datenquelle „SuperX“ angezeigt. Das betrifft vor allem Module, die modulübergreifend, auswertungsorientiert oder spezialisiert auf vorhandene SuperX-Daten zugreifen.

Beispiele hierfür können sein:

* kenn für Kennzahlen
* man für Managementberichte
* erfolg für Studienverlauf bzw. Erfolgsbetrachtungen
* gang für Studiengänge

Die Datenquelle „SuperX“ bedeutet also nicht, dass keine Daten verarbeitet werden. Sie zeigt an, dass die Verarbeitung auf Daten basiert, die bereits im SuperX-System vorhanden sind.

== Aktionen ausführen ==

Die verfügbaren Aktionen hängen vom jeweiligen Modul ab. Nicht jedes Modul unterstützt alle Aktionen. Wenn eine Aktion nicht verfügbar ist, wird der entsprechende Button nicht angezeigt oder ist nicht aktiv.

[[Bild:SuperX_ETL_Manager_Aktionsbuttons.png|Modulzeile mit den Aktionsbuttons Unload, Update, Unload & Update und Upgrade.]]

=== Unload ===

Die Aktion „Unload“ entlädt Daten aus einem angebundenen Vorsystem, sofern für das Modul ein Vorsystem angebunden ist.

Der Unload dient dazu, Daten aus der jeweiligen Datenquelle bereitzustellen, damit sie anschließend in SuperX verarbeitet werden können. Je nach Modul und Einrichtung kann der Unload auch dazu dienen, Daten für eine weitere Verarbeitung oder Übertragung bereitzustellen.

=== Update ===

Die Aktion „Update“ lädt vorhandene Rohdaten in SuperX ein und führt die Hauptladeroutine des Moduls aus.

Dies ist in vielen Fällen die wichtigste Aktion für den täglichen Betrieb. Beim Update werden die vorhandenen Rohdaten verarbeitet und die zugehörigen SuperX-Tabellen aktualisiert.

=== Unload & Update ===

Die Aktion „Unload & Update“ führt zuerst den Unload und anschließend das Update aus.

Diese Aktion ist sinnvoll, wenn neue Daten aus einem angebundenen Vorsystem entladen und direkt anschließend in SuperX verarbeitet werden sollen.

=== Upgrade ===

Die Aktion „Upgrade“ führt eine Modulaktualisierung durch. Dabei werden die Datenstrukturen des Moduls auf den ausgelieferten Stand gebracht.

Ein Upgrade sollte ausgeführt werden, wenn eine neue verfügbare Version angezeigt wird oder wenn dies im Rahmen eines Modulupdates erforderlich ist.

== Sonderfall Kennzahlen-Modul ==

Beim Kennzahlen-Modul „kenn“ ist die Verarbeitung etwas anders als bei typischen Modulen mit externem Vorsystem.

Die Datenquelle ist hier in der Regel „SuperX“. Das bedeutet, dass die Kennzahlen nicht primär aus einem externen Fremdsystem entladen werden. Stattdessen basiert die Verarbeitung auf Daten, die bereits in SuperX vorhanden sind.

Für den täglichen Betrieb ist beim Kennzahlen-Modul daher häufig vor allem die Aktion „Update“ relevant. Dabei werden die Kennzahlen auf Basis der vorhandenen SuperX-Daten neu berechnet bzw. aktualisiert.

Die Aktion „Unload“ kann beim Kennzahlen-Modul eine andere Bedeutung haben als bei klassischen Vorsystem-Modulen. Sie kann dazu dienen, Kennzahlen für ein anderes System bereitzustellen, zum Beispiel:

* für ein hochschulübergreifendes SuperX
* für Vergleichssysteme
* für landesweite Auswertungen oder Berichtssysteme

Die kombinierte Aktion „Unload & Update“ ist beim Kennzahlen-Modul daher nicht immer die wichtigste Aktion. In vielen Installationen wird das Update gezielt über die Oberfläche ausgeführt, während Export- oder Übertragungsprozesse über automatische Abläufe wie Cronjobs gesteuert werden können.

== Aktueller Lauf ==

Der Bereich „Aktueller Lauf“ zeigt Informationen zum zuletzt gestarteten oder aktuell laufenden ETL-Prozess.

Typische Informationen sind:

* JobExecutionId
* Name des gestarteten Jobs
* Status
* Fortschritt
* Anzahl der ausgeführten Schritte
* Log-Ausgabe

[[Bild:SuperX_ETL_Manager_Aktueller_Lauf.png|Bereich „Aktueller Lauf“ mit JobExecutionId, Status, Fortschritt und Log-Ausgabe.]]

=== Status ===

Der Status zeigt den aktuellen Zustand des Laufs. Häufige Statuswerte sind:

{| class="wikitable"
! Status
! Bedeutung
|-
| STARTING
| Der Lauf wird gestartet.
|-
| STARTED
| Der Lauf wurde gestartet und wird ausgeführt.
|-
| COMPLETED
| Der Lauf wurde erfolgreich abgeschlossen.
|-
| FAILED
| Der Lauf ist mit einem Fehler abgebrochen.
|-
| STOPPED
| Der Lauf wurde gestoppt.
|}

=== Fortschritt ===

Der Fortschritt zeigt, wie viele Prozessschritte bereits abgearbeitet wurden. Er ist als technischer bzw. prozessbezogener Fortschritt zu verstehen.

Wichtig ist: Der Fortschrittswert ist keine genaue Zeitprognose.

Ein Lauf kann schnell auf eine hohe Prozentzahl springen und dort längere Zeit stehen bleiben, wenn ein einzelner Verarbeitungsschritt besonders lange dauert. Umgekehrt können viele kleine Schritte sehr schnell nacheinander abgeschlossen werden. Die Prozentanzeige beschreibt daher den Abarbeitungsstand der Prozessschritte, nicht die tatsächlich vergangene oder verbleibende Zeit.

Beispiel:

Ein Lauf kann bereits 80 % anzeigen, obwohl noch ein größerer Verarbeitungsschritt aussteht. Ebenso kann ein Lauf am Anfang längere Zeit bei einer niedrigen Prozentzahl stehen bleiben, wenn ein früher Prozessschritt besonders umfangreich ist.

== Log-Ausgabe ==

Die Log-Ausgabe zeigt technische Informationen zum ausgeführten ETL-Prozess. Sie kann helfen, den Ablauf nachzuvollziehen und bei Problemen erste Hinweise zu erhalten.

Die Log-Ausgabe ist vor allem für Supportfälle hilfreich. Für eine tiefergehende Fehleranalyse sind in der Regel administrative Kenntnisse erforderlich. Je nach Fehler müssen zusätzlich Serverlogs, Datenbankinhalte, Moduldateien oder Systemkonfigurationen geprüft werden.

Wenn die Log-Ausgabe nicht sofort erscheint, kann sie über „Log laden“ erneut abgefragt werden. Gerade bei umfangreichen Läufen kann es vorkommen, dass die Log-Ausgabe erst kurze Zeit nach Abschluss vollständig verfügbar ist.

== Typische Nutzungsszenarien ==

=== Bereits vorhandene Rohdaten verarbeiten ===

Wenn die Rohdaten bereits vorhanden sind und lediglich erneut verarbeitet werden sollen, wird in der Regel die Aktion „Update“ verwendet.

Beispiel:

* Rohdaten liegen bereits im System vor
* Berechnungen oder Aggregationen sollen neu ausgeführt werden
* die SuperX-Tabellen des Moduls sollen aktualisiert werden

Geeignete Aktion:

<pre>
Update
</pre>

=== Neue Daten aus einem Vorsystem übernehmen und verarbeiten ===

Wenn neue Daten aus einem externen Vorsystem übernommen und anschließend verarbeitet werden sollen, kann die Aktion „Unload & Update“ verwendet werden.

Dabei werden zunächst die Daten aus dem Vorsystem entladen. Anschließend werden die Daten durch das Update in SuperX verarbeitet.

Geeignete Aktion:

<pre>
Unload & Update
</pre>

=== Nur Daten aus einem Vorsystem entladen ===

Wenn Daten aus einem Vorsystem entladen werden sollen, ohne direkt anschließend die Laderoutine auszuführen, kann die Aktion „Unload“ verwendet werden.

Geeignete Aktion:

<pre>
Unload
</pre>

=== Modul auf den ausgelieferten Stand aktualisieren ===

Wenn eine neue verfügbare Version angezeigt wird, sollte ein Upgrade geprüft bzw. durchgeführt werden.

Geeignete Aktion:

<pre>
Upgrade
</pre>

=== Kennzahlen innerhalb von SuperX aktualisieren ===

Beim Kennzahlen-Modul „kenn“ werden die Daten in der Regel aus SuperX selbst bezogen. Wenn die Kennzahlen neu berechnet oder aktualisiert werden sollen, ist häufig die Aktion „Update“ die passende Aktion.

Geeignete Aktion:

<pre>
Update
</pre>

=== Kennzahlen für ein anderes System bereitstellen ===

Wenn Kennzahlen für ein anderes System bereitgestellt werden sollen, kann beim Kennzahlen-Modul die Aktion „Unload“ relevant sein.

Dies kann zum Beispiel für hochschulübergreifende Auswertungen, Vergleichssysteme oder landesweite Berichtssysteme genutzt werden.

Geeignete Aktion:

<pre>
Unload
</pre>

== Hinweise zur Nutzung ==

Bei der Nutzung des ETL Managers sollten folgende Punkte beachtet werden:

* Ein laufender Prozess sollte nicht unnötig mehrfach parallel gestartet werden.
* Nach einem Lauf kann die Modulübersicht über „Aktualisieren“ neu geladen werden.
* Die Prozentanzeige ist kein Zeitindikator, sondern beschreibt den Fortschritt der Prozessschritte.
* Bei Fehlern sollte zuerst der Status und anschließend die Log-Ausgabe geprüft werden.
* Für tiefergehende Fehleranalysen sollten Administratorinnen und Administratoren oder technische Ansprechpartner einbezogen werden.
* Bei neuen verfügbaren Modulversionen sollte geprüft werden, ob ein Upgrade auszuführen ist.

== Details-Bereich ==

Über den Button „Details“ können zusätzliche technische Informationen zu einem Modul angezeigt werden.

Der Details-Bereich ist vor allem für fortgeschrittene Benutzerinnen und Benutzer, Administratorinnen und Administratoren oder den Support gedacht. Er kann unter anderem folgende Informationen enthalten:

* technische Modulkennung
* Systeminfo-ID
* technische Jobnamen
* verfügbare Jobs
* Rohdaten der Schnittstelle
* zusätzliche technische Moduldetails

Für den normalen Betrieb ist der Details-Bereich meist nicht erforderlich. Er ist vor allem dann hilfreich, wenn bei Rückfragen oder Supportfällen genaue technische Informationen benötigt werden.

== Diagnose-Bereich ==

Der Diagnose-Bereich ist eine technische Hilfsfunktion zur Prüfung der ETL-Manager-Installation. Er ist global angeordnet und nicht auf ein einzelnes Modul beschränkt.

Die Diagnose führt keine Reparaturen automatisch aus. Sie zeigt technische Informationen, mögliche Auffälligkeiten und Hinweise an. Zusätzlich können SQL- oder Shell-Hinweise angezeigt werden, die bei Bedarf von Administratorinnen und Administratoren kopiert und manuell ausgeführt werden können.

Der Diagnose-Bereich kann unter anderem folgende Informationen enthalten:

* Erreichbarkeit der REST-Schnittstellen
* Webapp-, Tomcat- und Java-Informationen
* Pfade und Dateisysteminformationen
* Festplattenspeicher
* Datenbankinformationen
* Prüfung der Log-Tabelle
* Versionsquellen
* bekannte Fehlerbilder
* kopierbare SQL- und Shell-Hinweise

Der Diagnose-Bereich ist vor allem für Administratorinnen und Administratoren oder technische Ansprechpartner gedacht. Für normale Anwenderinnen und Anwender ist er in der Regel nur dann relevant, wenn ein Fehler auftritt oder technische Informationen weitergegeben werden sollen.

== Administratorhinweise ==

Dieser Abschnitt enthält ergänzende technische Hinweise. Er richtet sich vor allem an Administratorinnen und Administratoren sowie an den technischen Support.

=== Herkunft der Versionsinformationen ===

Die Oberfläche zeigt eine installierte und eine verfügbare Version an.

Die installierte Version beschreibt den Stand, der in der Datenbank installiert ist. Falls die REST-Schnittstelle keinen Wert liefert, kann die Version aus der Tabelle <code>db_version</code> gelesen werden.

Die verfügbare Version beschreibt den ausgelieferten Stand im Dateisystem. Sie kann aus der Modul-XML-Datei gelesen werden. Für normale Module liegt diese Datei typischerweise unter:

<pre>
WEB-INF/conf/edustore/db/module/<modul>/conf/<modul>.xml
</pre>

Für das Kernmodul gilt ein Sonderfall. Die Modul-XML liegt unter:

<pre>
WEB-INF/conf/edustore/db/install/conf/kern.xml
</pre>

Zusätzlich kann eine Datei <code>VERSION</code> im jeweiligen Modulverzeichnis als Fallback verwendet werden.

=== Log-Tabelle ===

Die Log-Ausgabe des ETL Managers verwendet eine Datenbanktabelle für die Joblogs. Wenn diese Tabelle fehlt oder unvollständig ist, kann die Log-Ausgabe fehlschlagen.

Eine mögliche Struktur der Tabelle ist:

<pre>
CREATE TABLE IF NOT EXISTS job_log
(
job_instance_id bigint NOT NULL,
log text,
status text
);

CREATE UNIQUE INDEX IF NOT EXISTS ix_job_log1
ON public.job_log USING btree (job_instance_id);
</pre>

Diese SQL-Anweisungen sollten nicht automatisch durch die Oberfläche ausgeführt werden. Sie dienen als Hinweis für Administratorinnen und Administratoren und müssen bei Bedarf manuell geprüft und ausgeführt werden.

=== Typische technische Fehlerbilder ===

{| class="wikitable"
! Fehlerbild
! Mögliche Ursache
|-
| <code>/jobLog/{id}</code> liefert HTTP 500
| Die Tabelle <code>job_log</code> fehlt, ist unvollständig oder der Logeintrag ist noch nicht verfügbar.
|-
| <code>/job/list/{modul}</code> liefert HTTP 500
| Moduldateien fehlen, Pfade stimmen nicht oder die Webapp verwendet nicht den erwarteten Dateistand.
|-
| REST-Endpunkt liefert HTTP 404
| Der Context-Pfad, die Webapp, der Port oder ein Tunnel zeigt möglicherweise nicht auf die erwartete Anwendung.
|-
| Log erscheint erst nach erneutem Laden
| Der ETL-Lauf ist abgeschlossen, aber der Logeintrag war beim ersten Abruf noch nicht vollständig verfügbar.
|}

== Zusammenfassung ==

Der SuperX ETL Manager stellt eine zentrale Oberfläche zur Ausführung und Überwachung von ETL-Prozessen bereit. Für den täglichen Betrieb stehen vor allem die Aktionen „Unload“, „Update“, „Unload & Update“ und „Upgrade“ im Vordergrund.

Die Modulübersicht zeigt den Installationsstatus, Versionsinformationen, Datenquellen und Datenbankverbindungen. Der Bereich „Aktueller Lauf“ informiert über den Fortschritt eines gestarteten Prozesses. Die Log-Ausgabe liefert technische Zusatzinformationen und kann bei der Fehleranalyse helfen.

Details und Diagnose ergänzen die Oberfläche um technische Informationen für Support- und Administrationsfälle. Sie unterstützen bei der Analyse, führen aber keine automatischen Reparaturen aus.

= Installation und Verwaltung in der Shell mit Skripten =

== Installation von Modulen ==
Das Kernmodul enthält außer Administrationsabfragen und Tabellen keinerlei Inhalte. Die Inhalte werden in Form von Modulen hinzugefügt. Dazu gibt es vorgefertigte [[Kernmodul_Shellscripte#Modulverwaltung|Installationsscripte]].

=== Architektur von SuperX-Modulen ===
Die folgende Abbildung zeigt die Architektur von Modulen ab Beispiel vom HISCOB-Modul:

{| class="wikitable"
|-
!
!
|-
| Ein Modul besteht auf Datenbankseite aus Abfragen, Hilfstabellen, Datentabellen und Schlüsseltabellen (sowie Prozeduren).
Auf Webserver-Seite können auch XSL-Stylesheets vorhanden sein.
| [[Bild:modularchitektur_cob.png|417x307px]]
|}
Die Abbildung zeigt, dass ein Modul eigene Komponenten nutzt, aber auch auf Teile des Kernmoduls zugreift, z.B. das Orgranigramm - dies macht SuperX zu einem integrierten System. Neben dem Organigramm sind alle anderen Komponenten des Kernmoduls natürlich betroffen, z.B. Themenbaum, Userrechte.
Die Ordnerstruktur eines Moduls spiegelt die Komponenten des Systems wieder. Es gibt je ein Verzeichnis für datentabellen, schluesseltabellen und hilfstabellen.
Die Installation eines Moduls ist in der Dokumentation des jeweiligen Moduls näher beschrieben. Module, die auf dem Kernmodul 2.1 oder höher basieren, haben einen einheitlichen Aufbau.

=== Modulscripte im Kernmodul ===
Seit Version 2.1 werden die Datenbankschemata und Scripte der Module in einem einheitlichen Format zusammengestellt und in einer Datei $SUPERX_DIR/db/module/$MODULNAME/conf/$MODULNAME.xml gespeichert. Das XML-Format hat den Vorteil, dass die Scripte dynamisch für Postgres und Informix erzeugt werden können, und dass die Scripte vereinheitlicht werden. Aus dieser Datei werden die Scripte erzeugt, die das Modul jeweils für Postgres und Informix installieren / updaten /aktualisieren / überprüfen und entfernen. Die folgende Abbildung zeigt das Vorgehen:

{| class="wikitable"
|-
!
!
|-
| Aus der xml-Datei werden die jeweiligen Scripte für die Installation, den Update, die Extraktions-, Transformations- und Ladescripte (ETL) und die Deinstallation erzeugt.
| [[Bild:modulscripte_erzeugen.png|417x371px]]
|}

Die Modul-Scripte liegen als Shellscripte im Verzeichnis $SUPERX_DIR/db/bin, und sind an [[Kernmodul_Shellscripte#Modulverwaltung|anderer Stelle]] im Detail erläutert.

{| class="wikitable"
|-
!
!
|-
| module_install.x -name- -pfad-
z.B.:
module_install.x sos $SOS_PFAD
| Installiert ein Modul, d.h. erzeugt die Tabellen, Views, Funktionen und Abfragen. Die Abfragen werden in den Themenbaum eingehängt.
|-
| module_etl.x -name- -pfad-
z.B.:
module_etl.x sos $SOS_PFAD
| Aktualisiert das Modul, d.h. lädt die Rohdaten, Transformiert sie, und aggregiert die Hilfstabellen. Fehler werden in eine Log-Datei geschrieben, diese kann dann per Mail an einen Admin versandt werden. Wenn das Script erfolgreich durchläuft, wird die Tabelle systeminfo aktualisiert. 
Das Script wird nicht direkt als Cronjob aufgerufen, sondern von einem Shellscript, das die Umgebungsvariablen und Parameter setzt, z.B. cob_update.x.
|-
| module_drop.x -name- -pfad-
z.B.:
module_ drop.x sos $SOS_PFAD
| Entfernt das Modul bzw. die Tabellen, Views, Funktionen und Abfragen.
|-
| module_scripts_create.x -name- -pfad- -Datenbanksystem(optional, INFORMIX, POSTGRES)- -Versionsnr.-
| Erzeugt via XSL-Transformation die jeweiligen Scripte, die in den obigen Scripten aufgerufen werden, z.B. bau_install_ids.sql für das Installationsscript des Baumoduls beim Informix Dynamic Server.
|}

Neben den operativen Scripten erzeugt module_scripts_create.x auch html-Dateien zur Dokumentation eines Moduls in
$SUPERX_DIR/db/module/-Modulname-/conf/-Modulname-.html
(auch als rtf-Datei zu Einbindung in Modul-Dokumentationen) sowie zur Schnittstelle in
$SUPERX_DIR/db/module/-Modulname-/rohdaten/-Modulname-_unload.html
Darüber hinaus werden auch DBForms-Formulare erzeugt.

=== Installation eines Moduls: Allgemeines Vorgehen ===
Das Vorgehen bei der Installation eines Moduls ist standardisiert. Im folgenden eine Kurzbeschreibung, weiter unten finden Sie das Vorgehen am Beispiel des ZUL-Moduls im Detail.
* Entpacken Sie das Modul in $SUPERX_DIR
* Erweiterung der Umgebung in der Datei $SUPERX_DIR/db/bin/SQL_ENV: fügen Sie den Inhalt der jew. Beispieldatei SQL_ENV_-Modulname-.sam in der SQL_ENV an, wenn noch nicht vorhanden, und ändern Sie ggf. Email-Adressen für log- und Fehlermails.
* Entladen der Rohdaten; auch hier müssen vorher Umgebungsvariablen zum Vorsystem angepasst werden 
(Datei $-Modulname-_LOAD_PFAD/-Modulname-_ENV), hier liegt ebenfalls eine *.sam-Datei vor
* Kopieren der Rohdaten nach -Modulpfad-/rohdaten. Neuere SuperX-Module haben dafür vorgefertigte Scripte mit dem Namen -Modulname-_copy.x (z.B. zul_copy.x)
* Installieren Sie das Modul mit -Modulname-_erzeugen.x, z.B. mit zul_modul_erzeugen.x
* Wenn die Installation erfolgreich war, können Sie das Modul aktualisieren mit 
-Modulname-_update.x (ggf. mit Parametern) 
z.B. mit
zul__update.x
d.h. die ETL-Prozesse werden gestartet (s.u.).
* Wenn das Modul erfolgreich aktualisiert ist, wird eine Prüfprozedur gestartet, die die Daten plausibilisiert. Fehler und Warnungen finden Sie in der Datei $-Modulname-_ERRORDAT.
* Starten Sie Tomcat neu. Wenn Tomcat auf einem separaten Server installiert ist, müssen Sie vorher die Datei $SUPERX_DIR/webserver/tomcat/webapps/superx/WEB-INF/dbforms-config.xml dorthin übertragen.
* Schritt 7 wird bei jedem SuperX-Update wiederholt. Nun muss der Entladerhythmus geplant werden, und die Cronjobs werden eingerichtet. Es gibt eine Musterdatei $SUPERX_DIR/db/module/-MODULNAME-/-MODUL-_update_cron.x.sam , benennen sie diese um nach -MODUL-_update_cron.x und fügen Sie das Script in die crontab ein.

==== Allgemeines zum Laden ====
Zunächst müssen die Rohdaten aus dem Vorsystem entladen werden.
Für das Entladen gibt es ferner zwei Modi: Das "Pull"-Verfahren und das "Push"-Verfahren.
* Beim '''"Pull"-'''Verfahren wird einer Benutzerkennung auf dem SuperX-Rechner Zugriffsrecht auf die SOSPOS-Datenbank gegeben, und die Daten werden via TCP/IP aus dem Basissystem entladen. Bei APP / HISinOne als Quellsystem ist "Pull" das Standardvorgehen.
* Beim '''"Push"-'''Verfahren werden die Entladescripte auf den SOSPOS-Rechner kopiert und dort von einer Benutzerkennung auf dem SOSPOS-Rechner ausgeführt. Die Rohdaten müssen dann auf den SuperX-Rechner kopiert werden. Dieses Verfahren klappt bei Informix unter Unix problemlos, bei Entladen aus Postgres müsste das komplette SuperX-Kernmodul installiert werden.
Am einfachsten ist immer das "Pull"-Verfahren, das mit fast allen Quellsystemen funktioniert und wenig Konfiguration auf dem Quellsystem erfordert. Aufgrund von Sicherheitsvorkehrungen oder Netz-Infrastrukturen wählen aber viele Hochschulen das "Push"-Verfahren. Da derzeit Informix /Unix die gängigste Plattform an Hochschulen ist, ist dies auch kein Problem.

==== Einrichtung der Entladescripte ====
Im Push-Verfahren btw. unter SuperX können Sie mitgelieferte Shellscripte nutzen. Das folgende Beispiel des ZUL-Moduls zeigt das Vorgehen:
Die Entladescripte liegen im Verzeichnis $SUPERX_DIR/db/module/zul/rohdaten und lauten je nach Systemversion:
zul_unload.x

Die Scripte laufen nur, wenn die entsprechenden Umgebungsvariablen in der Datei ZUL_ENV (im gleichen Verzeichnis, ein Muster liegt vor in ZUL_ENV.sam) korrekt gesetzt sind, benennen Sie die Musterdatei um nach ZUL_ENV und tragen die richtigen Umgebungsvariablen ein, z.B. den Pfad für $INFORMIXDIR.
'''ZUL_ENV Die Umgebung für Entladescripte aus ZUL-GX(Auszug)'''
##Pfad für Entladedaten:
ZUL_PFAD=.; export ZUL_PFAD
##hier muss Unterverzeichnis unl existieren!

In der ZUL_ENV müssen außerdem folgende Umgebungsvariablen gesetzt werden (defaults sind bereits vorbelegt, aber hier und da müssen Sie sicher ran):
{| class="wikitable"
|-
! Variable
! Erläuterung
|-
|
| '''Nur für Informix gelten:'''
|-
| INFORMIXDIR
| Home-Verzeichnis von Informix
|-
| INFORMIXSERVER
| Name des Informixservers
|-
| ONCONFIG
| Name der onconfig, wenn auf dem SOS-Rechner mehrere Informix-Instanzen laufen
|-
| CLIENT_LOCALE
| Sprachumgebung (wichtig fürs Entladen von Datumsformaten)
|-
| SERVER_LOCALE
| dito
|}

{| class="wikitable"
|-
! Variable
! Erläuterung
|-
|
| '''Nur für Postgres gelten:'''
|-
| PGDATESTYLE
| Datumsformat "German"
|-
| PGPORT
| Port vom Postgres-Server, standardmäßig 5432
|-
| PGHOST
| Hostname oder IP-Adresse vom Postgres-Server
|-
| PGUSER
| Benutzerkennung für Postgres-Server (nur Datenbank, nicht Betriebssystem)
|-
| PGPATH
| Installationsverzeichnis von Postgres, z.B. /usr/local/pgsql
|-
| DB_PROPERTIES
| Pfad zur db-zul.properties-Datei mit den Zugangsparametern für SOSPOS unter Postgres
|-
| LOGGING_PROPERTIES
| Pfad zur Steuerungsdatei mit den Parametern für das Logging beim Entladen, voreingestellt auf ./logging.properties. Normalerweise brauchen Sie hier nichts ändern, wenn beim Entladen Probleme auftauchen, kann man den Level von SEVERE auf INFO oder FINEST ändern, dann werden die konkreten SQLs geloggt. Aber Achtung: wenn keine Fehler mehr auftreten, müssen Sie den Level wieder auf SERVERE ändern, sonst kommen Schlüsselworte in die Logdatei zul_unload.err, die dann bei der Übernahme nach SuperX fälschlicherweise zu Fehlermeldungen führen.
|}
Unter Postgres muss für das "Pull"-Verfahren beim Entladen die Datenbankverbindung in der Datei db-zul.properties eingetragen werden (Muster für Postgres liegt bei in db-zul_pg.properties). Dazu laden Sie einmal die Datei ZUL_ENV mit den obigen Parameter, starten den SuperX-Propadmin (siehe Administrationshandbuch Kernmodul) und richten die Verbindung zum SOSPOS-Server ein. Das Kennwort wird verschlüsselt gespeichert. Danach sind die Entladescripte für Postgres ausführbar.
Hinweis: Anders als Informix hat Postgres hat eine eigene, vom Basissystem unabhängige Benutzerverwaltung. Daher brauchen Sie den User, den Sie zum Entladen aus Postgres nutzen, nicht auf dem SuperX- oder SOSPOS-Rechner auf Betriebssystem-Ebene einrichten. Sie können also z.B. auf dem SuperX-Rechner zum Entladen aus SOSPOS die Kennung sospos des Postgres- Rechners verwenden. Oder Sie richten in der SOSPOS -Datenbank den Benutzer SuperX ein und geben ihm Leserecht auf die Tabellen sowie das Recht, Tabellen und Stored Procedures anzulegen.

{| class="wikitable"
|-
! Variable
! Erläuterung
|-
|
| '''Für alle Platformen gelten folgende Variablen:'''
|-
| ERRORMAIL
| An wen solle eine Logmail verschickt werden, wenn das Entladen nicht geklappt hat? (nur Unix).
|-
| LOGMAIL
| An wen soll immer eine Logmail verschickt werden
|-
| MAILPROG
| Pfad zum ausführbaren Mailprogramm unter Unix, Vorbelegung ist "mail", manche Unixe haben aber auch "mutt" oder "mailx".
|-
|
| Wenn die Rohdaten beim Push-Verfahren nach dem Entladen vom ZUL-Rechner auf den SuperX-Rechner kopiert werden sollen, dann werden für das Script zul_copy.x folgende Umgebungsvariablen benötigt:
|-
| COPY_METHOD
| Programm, das die Dateien kopiert; rsync und scp sind wählbar.
|-
| REMOTE_DIR
| Verzeichnis, in das die Rohdaten auf dem SuperX-Rechner kopiert werden sollen, in der Regel ist dies "/home/superx/db/module/zul/rohdaten"
|-
| REMOTE_USER
| Der Unix-Username auf dem SuperX-Rechner, in der Regel "superx".
|-
| REMOTE_HOST
| Der Rechnername bzw. die IP-Nr. des SuperX-Rechners.
|}
Dann starten Sie das Script zul_unload.x. Wenn es gelaufen ist, müssten die Dateien im unl-Verzeichnis stehen. Prüfen Sie dann bitte, ob dort Dateien mit 0 bytes stehen. Die Logdatei heisst zul_unload.err.

===== Entladen unter Windows =====
Für das Entladen unter Windows gibt es Muster-Dateien im jew. Rohdaten-Verzeichnis, z.B. $SOS_PFAD/rohdaten/sos_unload.bat. Die Einrichtung geschieht dann in [[Kernmodul_Komponentenverwaltung#Java-Client_zum_Entladen_von_Quell-Datenbanken|Java]]. Ans Ende der Datei können Sie noch schreiben:
date /T >superx.datum
Dann wird auch die Datumsdatei geschrieben.

===== Dateitransfer beim Push-Verfahren =====
Wenn Sie das Verzeichnis nicht gemounted haben, müssen das Verzeichnis unl, die zul_unload.err und die superx.datum dann in das Verzeichnis $ZUL_LOAD_PFAD auf dem SuperX-Rechner kopiert werden, ein Script dafür liegt ebenfalls bei (zul_copy.x). Das Entladedatum wird danach in der Textdatei $ZUL_LOAD_PFAD/superx.datum gespeichert; wenn das Script einen Fehler findet, dann wird das vorherige Datum (in der Datei superx.datum.alt) gesetzt.

Für den Transfer der Rohdaten beim Push-Verfahren wird in SuperX die dateibasierte Schnittstelle genutzt. Unter UNIX läßt sich dieser Transfer vollends automatisieren, indem die Programme scp oder rsync auf der Basis des OpenSSH-Pakets genutzt werden. Beide setzen auf das ssh-Protokoll 2 auf und stellen somit einen verschlüsselten Dateitransfer sicher. Auch [[Kernmodul_Komponentenverwaltung#Einrichtung_von_SFTP|sftp]] ist möglich.
In den jeweiligen Modulen wird im Verzeichnis rohdaten eine Beispieldatei mit dem Namen -MODULNAME-_ENV.sam ausgeliefert, die Sie umbenennen können nach -MODULNAME-_ENV. Darin werden am Ende der Datei die Parameter zum Kopieren festgelegt, also die Userkennung REMOTE_USER, der Hostname REMOTE_HOST, und die Methode des Kopierens (COPY_METHOD) sowie die jeweiligen Zielpfade. Diese Umgebungsvariablen werden von dem jeweiligen Script -modulname-_copy.x benutzt.

===== Entfernen der Passworteingabe unter Unix =====
Damit die Passworteingabe unter Unix entfällt, muss man wie folgt vorgehen:
Loggen Sie sich zunächst testweise einmal ein. Wenn Sie z.B. vom COB-Server auf den SuperX-Server kopieren wollen, loggen Sie sich als user cob auf cobhost ein mit 
ssh superx@superxhost
Beim ersten Mal müssen Sie die Sicherheitsabfrage mit "yes" bestätigen.
Erzeugen Sie auf dem Quellrechner einen öffentlichen Schlüssel mittels

ssh-keygen -t ed25519 -C "cob@cobhost"

wobei man eine leere Passphrase vergibt. Der öffentliche Teil dieses Schlüssels (~/.ssh/id_ed25519.pub) muss auf dem Zielrechner in die Datei ~/.ssh/authorized_keys eingefügt werden, ggf. muss die Datei neu erzeugt werden.
Wenn z.B. auf dem COB-Server unter der Kennung cob ein Key wie folgt erzeugt wurde:

;Beispieleintrag eines Public Keys:

ssh-ed25519 AAAAC3N.[hier viele kryptische Zeichen]....4V cob@cobhost

Dann wird genau diese Zeile in der Datei /home/superx/.ssh/authorized_keys angefügt (die Datei kann mehrere PublicKeys enthalten, ein Eintrag pro Absatz).
Achten Sie auch auf Dateirechte: Die Verzeichnisse und Dateien sollten keine Schreibrechte für Gruppen haben. Im Zweifelsfall z.B. für den user superx:
chmod 700 /home/superx/.ssh
chmod 700 /home/superx/.ssh
chmod 600 /home/superx/.ssh/authorized_keys
Danach sollte z.B. der Login vom cobhost als user cob mit ssh superx@superxhost ohne Passworteingabe klappen. Wenn nicht, schalten Sie das Logging mit ssh -v superx@superxhost ein. Eine Möglichkeit ist, dass die PublicKey-Authentifizierung in der Konfigurationsdatei des SSHD (normal /etc/ssh/ssh_config) abgeschaltet ist. Weitere Diagnosen liefert die Datei /var/log/messages.
Sie können außerdem noch einschränken, von welchem Host die obige Authentifizierung ermöglicht wird. Dazu setzen Sie den Parameter "from=*.uni-xy.de" davor, z.B.

{| class="wikitable"
|-
!
!
|-
| Einschränkung "from" 
in authorized_keys
| from="*.uni-xy.de" ssh-rsa AAAAB3Nza…[hier viele kryptische
Zeichen]…pg6VkCc= cob@cobhost
|}

Wenn Sie die Kopiermethode scp benutzen, und die obige "authorized_keys"-Metohde mit PublicKey nicht nutzen wollen, können Sie auch mit Private Keys arbeiten (siehe SSH-Doku). Dazu können sie in der *_ENV-Datei in dem Parameter SCP_OPTS den Verweis auf den private Key setzen.
{| class="wikitable"
|-
!
!
|-
| SCP_OPTS in *_ENV: 
Beispiel COB_ENV
| SCP_OPTS="-p -B -i /home/cob/.ssh/superx_key"
export SCP_OPTS
|}

===== Entfernen der Passworteingabe unter Windows =====
Wenn Sie die ssh-Shell putty aus dem Installationspaket nutzen, haben Sie im Installationsordner auch die Anwendung "puttyGen.exe". Wenn Sie putty als reine Executable nutzen, laden Sie die Anwendung separat herunter. [http://winscp.net/download/puttygen.exe PuttyGen]
* Folgen Sie der Anleitung auf der Seite http://winscp.net/eng/docs/ui_puttygen, um den SSH2-DSA oder RSA Schlüssel zu erzeugen. Für den Schlüssel bitte kein Passwort vergeben, wenn Sie das Tool automatisiert nutzen.
* Den privaten Schlüssel geben Sie in Putty bzw. Winscp im Menü "Session" im Feld "Private Key File" an.
* Der Button "Save public key" ist nicht für OPENSSH unter Linux als Zielserver geeignet. Im folgenden Screenshot sehen Sie den markierten Bereich, den Sie kopieren müssen:
[[Bild:puttygen.png|413x402px]]
* Kopieren Sie Ihren Public Key, den Sie oben mit PuttyGen erzeugt haben, zur Datei "authorized_keys" und kopieren Sie diese in das Verzeichnis ~/.ssh/
* Im Profil unter Connection -> SSH -> Auth -> Credentials geben Sie den Pfad zum privaten Schlüssel in "Private key file" an.
* Bei erneutem Login mit Putty oder Winscp sollte die Passwortabfrage entfallen.

===== Einrichtung von SFTP (Server) =====
Beim Push-Verfahren wird, wenn mit scp oder rsync kopiert wird, eine Login-Shell vorausgesetzt. Wenn dies aus Sicherheitsgründen nicht gewünscht ist bzw. wg. Einsatz von Windows nicht möglich ist, können Sie auch sftp nutzen, dies wird in modernen ssh-Servern mitgeliefert und bietet ebenfalls verschlüsselten Datentransfer. Zur Einrichtung des Servers:
Der SSH-Dienst wird wie folgt konfiguriert (am Beispiel Ubuntu Linux 22.04 LTS) mit dem SFTP-Verzeichnis /home/sftp/-benutzername:

In der Datei /etc/ssh/sshd_config die Zeile auskommentieren:
#Subsystem sftp /usr/lib/openssh/sftp-server
und stattdessen:
Subsystem sftp internal-sftp
Match Group sftponly
ChrootDirectory /home/sftp/%u
ForceCommand internal-sftp
AllowTcpForwarding no

Danach starten Sie den SSH-Dienst neu:
service ssh restart

Dann legen Sie die Gruppe "sftponly" an:
groupadd sftponly
und dann den Unix-User an, und geben ihm die Gruppe "sftponly". Hier ein Script:
#!/bin/sh
SFTPUSERNAME=$1
mkdir -p /home/sftp/$SFTPUSERNAME
useradd -b /home/sftp -s /bin/false -G sftponly $SFTPUSERNAME
chown root:root /home/sftp/$SFTPUSERNAME
chmod 755 /home/sftp/$SFTPUSERNAME
mkdir -p /home/sftp/$SFTPUSERNAME/incoming
chown $SFTPUSERNAME:sftponly /home/sftp/$SFTPUSERNAME/incoming

Danach legen Sie mit
passwd $SFTPUSERNAME
ein Passwort fest.

Der User kann sich dann nicht mehr mit ssh einloggen, nur noch mit sftp, und landet beim Login in /home/$KENNUNG, in einem "chroot-Käfig", und der User kann mit SFTP in den Ordner "incoming" schreiben. Zum Testen geben Sie ein:
sftp $KENNUNG@-Host-

Wenn beim SFTP Login die Meldung kommt:
client_loop: send disconnect: Broken pipe
müssen Sie darauf achten dass das Home-Verzeichnis des Users nicht dem User gehört, sondern root.

Wenn der Login klappt, können Sie nach dem [[Kernmodul_Komponentenverwaltung#Entfernen_der_Passworteingabe_unter_Unix|oben]] beschriebenen Verfahren die Passworteingabe durch PublicKey-Authentifizierung ersetzen.

===== Einrichtung von SFTP =====
Für das Kopieren der Rohdaten können Sie im Kopierscript "-modulname-_copy.x" auch sftp-Kommandos nutzen. Sie müssen nur in der ENV-Datei die Variable
COPY_METHOD=sftp
setzen. Alle anderen Variablen und Mechanismen wie z.B. [[Kernmodul_Komponentenverwaltung#Entfernen_der_Passworteingabe_unter_Unix|Entfernen der Passworteingabe]] entsprechen denen von SCP / SSH (s.o.).
Spezielle Optionen fürs sftp können Sie in der Umgebungsvariable SFTP_OPTS setzen. Es kann z.B. sein, dass das Kopieren großer Dateien in einen Timeout läuft. Bei CSV bietet es sich an, die Dateien zu komprimieren, sie können also setzen:
SFTP_OPTS="-oCompression=yes"
export SFTP_OPTS
Danach wiederholen Sie das kenn_copy.x
Dies ist nur ein Beispiel. Weitere Optionen für SFTP entnehmen Sie der manpage.
Das Kopieren mit sftp klappt übrigens auch unter Windows z.B. mit dem Programm [http://winscp.net/eng/docs/lang:de winscp]. Dies wird im folgenden erläutert.

===== Einrichtung von SFTP unter Windows =====
Unter Windows ist das Standardprogramm für SFTP die Anwendung [http://winscp.net/eng/docs/lang:de winscp]. Sie können die Passworteingabe analog zu Putty [[Kernmodul_Komponentenverwaltung#Entfernen_der_Passworteingabe_unter_Windows|entfernen]]. Danach können Sie eine Session erzeugen:

[[Bild:winscp1.png|517x364px]]

Im Feld "Private key file" geben Sie den private key ein, den Sie [[Kernmodul_Komponentenverwaltung#Entfernen_der_Passworteingabe_unter_Windows|oben]] erzeugt haben. Klicken Sie dann auf "Save session", und geben Sie einen kurzen, sprechenden Namen ohne Leerzeichen oder Umlaute, z.B. "superx@vmmulti1"
Sie müssen nun die Verzeichnisse lokal und remote in der Winscp-Session speichern, im Menüpunkt "Directories":

[[Bild:winscp2.png|517x359px]]

Vergessen Sie auch hiernach nicht, die Session zu speichern.
Danach testen Sie einmal den Zugang. Wenn das klappt können Sie Winscp auch für die Kommandozeile automatisieren. Sie erzeugen zunächst eine Textdatei mit den Kommandos für Winscp, dies enthält auch die zu übertragenden Dateien. Der Aufbau der Datei ist wie folgt:
open -Sessionname-
# Upload the file to current working directory
put -Datei-
# Disconnect
close
# Exit WinSCP
exit

Die zu übertragenden Dateien sind in der Musterdatei des jew. Moduls in rohdaten/-Modulname-_sftp.txt aufgelistet, Sie müssen lediglich
* den "/" durch einen "\" ersetzen
* das Entladeprotokoll -Modulname-_unload.err und die Datumsdatei superx.datum hinzufügen
Hier ein Beispielscript fürs das Studierenden-Modul:
open superx@vmmulti1
# Change remote directory
# Upload the file to current working directory
put sos_unload.err
put superx.datum
put unl\konstanten.unl
put unl\sos_studenten.unl
put unl\sos_hzb.unl
put unl\sos_faecher.unl
put unl\sos_pord_to_stg.unl
put unl\sos_pruefungenext.unl
put unl\sos_pruefungen.unl
put unl\sos_lab_astat_attributes.unl
put unl\sos_stud_loe.unl
put unl\sos_faecher_ext.unl
put unl\sos_faecher_kontrolle.unl
put unl\sos_pruefungen_kontrolle.unl
put unl\sos_anschri.unl
put unl\sos_parstg.unl
put unl\sos_hsnr.unl
put unl\semester.unl
put unl\cif.unl
put unl\cifx.unl
put unl\k_pvers.unl
put unl\k_stg.unl
put unl\k_stgext.unl
put unl\k_abstgv.unl
put unl\sos_pord.unl
put unl\sos_dipl.unl
put unl\sos_minder.unl
put unl\sos_stud_d.unl
put unl\sos_pords.unl
put unl\sos_porg.unl
put unl\sos_labzuord.unl
put unl\sos_pnrzuord.unl
put unl\sos_gewichtungsvariante.unl
put unl\sos_gewichtungregel_filter.unl
put unl\sos_gewichtungregel.unl
put unl\personattribute.unl
put unl\personattributetype.unl
put unl\personattribute_value_list.unl
put unl\stu_update_prot.unl
put unl\exa_update_prot.unl
put unl\sos_accredited_ects.unl
put unl\sos_pord_orgeinheit.unl
# Disconnect
close
# Exit WinSCP
exit

Die Datei hat z.B. den Namen winscp_example_script.txt. Dann können Sie das Script aufrufen mit dem DOS-Kommando:
winscp /script=-Pfad zu-\winscp_example_script.txt

Hier ein Screenshot wie das dann aussieht:

[[Bild:winscp3.png|609x337px]]

Das DOS-Kommando läßt sich dann über die Windows-Taskverwaltung automatisieren.

===== Java-Client zum Entladen von Quell-Datenbanken =====
Zum Entladen aus dem operativen Vorsystem wird unter Informix dbaccess genutzt. Unter Postgres wird generell der SuperX-JAVA-Client zum Entladen genutzt, denn SuperX benötigt ein spezielles, an Informix angepasstes [[Kernmodul_Komponentenverwaltung#Format_der_Unload_Dateien_CSV|CSV-Format]], das sich mit Bordmitteln von Postgres (copy-Befehl) nicht erzeugen lässt. Es kann aber auch sinnvoll sein, aus der Informix-Datenbank mit SuperX-JAVA-Client zu entladen, z.B. wenn Sie kein UNIX-dbaccess auf dem Vorsystem installiert haben.

Wenn Sie das jew. operative Vorsystem im PUSH-Verfahren entladen wollen, d.h. die Rohdaten werden auf dem Vorsystem entladen und auf den SuperX-Rechner kopiert, dann müssen Sie spezielle Vorkehrungen treffen. SuperX nutzt generell zum Entladen eigene Java-Klassen. Beim Entladen im PULL-Verfahren sind diese Klassen vorhanden, denn die Entladeroutine läuft auf dem SuperX Rechner. Wenn Sie aber PUSH nutzen wollen, werden die SuperX-Java-Klassen auf dem Liefersystem benötigt, und die Entladeroutine muss konfiguriert sein. Im Folgenden nutzen wir das Beispiel "Entladen im Push-Verfahren aus SVA-GX unter Postgres". Gehen Sie dazu wie folgt vor:
* Kopieren Sie die Dateien
** superx*jar
** postgresql-*.jar
** jfor-0.7.2rc1.jar
* vom SuperX-Rechner im Verzeichnis $SUPERX_DIR/tomcat/webapps/superx/WEB-INF/lib auf den Quellrechner in ein Unterverzeichnis lib unter rohdaten (z.B. /home/sva/superx/rohdaten/lib). In rohdaten liegt die bisherige Entladeroutine (z.B. sva_unload.x).
* Kopieren Sie die *_ENV.sam -Datei nach *_ENV, also hier SVA_ENV.sam nach SVA_ENV
* Fügen Sie dann folgenden Passus in die Umgebungs-Datei der Entladeroutine, hier also SVA_ENV:
#Pfad zu den SuperX-Java-Libraries
#Der JDBC_CLASSPATH enthält alles, was der jdbc-Client in superx für den Datenbankzugriff braucht.
#jfor*.jar, postgresql*.jar
JDBC_CLASSPATH="$SVA_LOAD_PFAD/lib/superx5.0.jar:$SVA_LOAD_PFAD/lib/postgresql-42.2.19.jar:$SVA_LOAD_PFAD/lib/jfor-0.7.2rc1.jar"
export JDBC_CLASSPATH

Wenn dann noch die Variablen [[Kern_Installation_Upgrade#Anpassen_der_Datenbankparameter_db.properties|DB_PROPERTIES]] und LOGGER_PROPERTIES korrekt gesetzt sind, kann die Entladeroutine bei SX_CLIENT=jdbc (Wenn Sie unter Windows entladen, oder Informix ohne dbaccess entladen wollen) oder SX_CLIENT=psql (wenn Sie Postgres unter UNIX nutzen) mit Java entladen.

Danach können Sie das Entladescript ausführen:
sva_unload.x
Die Logdatei lautet sva_unload.err

Zum Kopieren der Rohdaten zum SuperX-Server passen Sie folgende Variablen an:

{| class="wikitable"
|-
! Variable
! Erläuterung
|-
|
| Wenn die Rohdaten beim Push-Verfahren nach dem Entladen vom SVA-Rechner auf den BI-Rechner kopiert werden sollen, dann werden für das Script sva_copy.x folgende Umgebungsvariablen benötigt:
|-
| COPY_METHOD
| Programm, das die Dateien kopiert; rsync, [[Kernmodul_Komponentenverwaltung#Einrichtung_von_SFTP|sftp]] und scp sind wählbar [Achtung: diese müssen dann betriebssystemseitig installiert sein].
|-
| REMOTE_DIR
| Verzeichnis, in das die Rohdaten auf dem BI-Rechner kopiert werden sollen, in der Regel ist dies "/home/superx/db/module/sva/rohdaten"
|-
| REMOTE_USER
| Der Unix-Username auf dem BI-Rechner, in der Regel "tomcat" oder "superx".
|-
| REMOTE_HOST
| Der Rechnername bzw. die IP-Nr. des BI-Rechners.
|}
Danach starten Sie
sva_copy.x
Die Logdatei lautet sva_copy.err

Weitere Entladeparameter werden in den modulspezifischen Administrationshandbüchern beschrieben.
{{Hinweis|Bei neuen SuperX-Versionen reicht es in der Regel, die modulspez. Dateien auszutauschen, also hier sva_unload.* etc.}}

== Update eines Moduls: Allgemeines Vorgehen ==
Wenn das Entladen aus dem Vorsystem geklappt hat (sofern es ein Vorsystem gibt), können Sie die Daten laden. Zum Update bzw. zum Laden der Rohdaten gehen in das Verzeichnis $SUPERX_DIR/db/module/-Modulname- und führen das Script aus:
-Modulname-_update.x
Die Logdatei lautet L_-Modulname-_UPDATE.log, im Mandantenfähigen Betrieb "L_-Modulname-_UPDATE-MANDANTID-.log".
Für die Aufnahme der Laderoutine in die crontab gibt es im gleichen Verzeichnis Musterscripte nach dem Namensmuster:
-Modulname-_update_cron.x
Je nach Push/Pull-Szenario können Sie auch den Unload darin starten oder nicht.

=== Modulupdate in mandantenfähigen Installationen ===
Der Modulupdate in mandantenfähigen Installation findet in einer SuperX-Installation statt, allerdings werden die einzelnen Scripte mit unterschiedlichen Umgebungsvariablen, wie sie in SQL_ENV.-MANDANTID- definiert ist, z.B. SQL_ENV.FHRO.
In der SQL_ENV.-MANDANTID- werden unterschiedliche Pfade für den jeweiligen *_LOAD_PFAD gesetzt, wobei in der Regel die Mandandid ein Unterverzeichnis vom "normalen" LOAD_PFAD ist. So ist z.B. beim COB-Modul folgender Pfad anzusetzen:
Normale SuperX-Installation:
COB_LOAD_PFAD=$SUPERX_DIR/db/module/cob/rohdaten
Mandantenfähige SuperX-Installation:
COB_LOAD_PFAD=$SUPERX_DIR/db/module/cob/rohdaten/FHRO
Unterhalb von FHRO befindet sich noch einmal die Entladeroutine sowie das Unterverzeichnis unl mit den Rohdaten. Dieses Verzeichnis FHRO kann der Einfahheit halber auch ein symbolischer Link auf den gemounteten COB-Rechner sein.
Durch Setzen der Mandantennummer in der Umgebungsvariable MANDANTID in der jeweiligen SQL_ENV des Mandanten werden die ETL-Scripte anders ausgeführt: Die Logdateien werden jeweils mit der Mandantennummer versehen (z.B. L_cob_updateFHRO.log), damit die Übersicht nicht verloren geht und der gleichzeitige Update mehrerer Mandanten in eine rsuperX-Installation möglich ist.
Außerdem können weitreichende Steuerungsmechanismen im Modulupdate eingesetzt werden: Nach jedem ETL-Schritt können optional mandantenspezifische Scripte aufgerufen werden. Diese müssen folgende Namenskonvention einhalten:
-Scriptname-_-MANDANTID-.sql
Also für eine hochschulspezifische Transformation im COB-Modul des Mandanten FHRO wird eine Datei namens
cob_trans_FHRO.sql
mit entsprechenden SQL-Anweisungen angelegt.

=== Format der Unload Dateien CSV ===
Generell gilt das Prinzip, daß Daten vom Vorsystem in CSV entladen werden, und dann in sog. Ladetabellen hochgeladen werden. Da CSV je nach DBMS unterschiedlich implementiert wird, hier eine kurze Beschreibung des Formats, das im wesentlichen den Vorgaben von Informix LOAD entspricht:
* Zeichenformat: UNIX LATIN1 oder UTF-8
* Feldtrenner: ^
* Satztrenner: Feldtrenner + UNIX NEWLINE
* Zeilenschaltung: Umbrüche innerhalb von Textfeldern sind als \ + NEWLINE codiert
* Feldtrenner, die im Textfeld vorkommen, werden mit "\" maskiert. Ebenso das Zeichen "\" selbst
* Die Datumsformate sind bei Datumsfeldern immer im deutschen Format (DD.MM.YYYY) vorgesehen
* Boolean-Werte werden durch "true" oder "false" codiert
* Der Dezimaltrenner ist ".", kein 1000-er Punkt bei Zahlen.
* Leerstrings und Leerzeichen werden als " " (Leerzeichen) exportiert.

== Upgrade eines Moduls: Allgemeines Vorgehen ==
Zum Upgrade bzw. zum Zurücksetzen des Moduls auf den Auslieferungszustand entpacken Sie das Paket in $SUPERX_DIR und gehen in das Verzeichnis $SUPERX_DIR/db/module/-Modulname-/upgrade und führen das Script aus:
-Modulname-_upgrade.x
Ausnahme: beim Kernmodul gibt es i.d.R. ein spezielles [[Kern_Installation_Upgrade#Standardvorgehen_beim_Upgrade|Upgrade Script]].

Die Logdatei lautet upgrade.log, im Mandantenfähigen Betrieb "upgrade-MANDANTID-.log".

Wenn Sie einen separaten Tomcat-Rechner betreiben, müssen Sie das Paket dort ebenfalls entpacken, und vom Datenbankserver die Datei $SUPERX_DIR/webserver/tomcat/webapps/superx/WEB-INF/dbforms-config.xml an die gleiche Stelle auf den Tomcat Rechner kopieren. Ein nochmaliges Ausführen des Upgrade Scriptes ist nicht nötig, weil dies nur die Datenbank betrifft.

== Hochschulspezifische Anpassung eines Moduls ==
=== Dateibasierte hochschulspezifische Anpassung ===
Nach der Installation bzw. beim Upgrade können Sie hochschuleigene SQL Scripte ausführen lassen. Erzeugen Sie dazu eine Datei
$SUPERX_DIR/db/module/-Modulname-/conf/customize.sql
bei Mandantenbetrieb
$SUPERX_DIR/db/module/-Modulname-/conf/customize-MANDANTID-.sql
und füllen Sie diese mit einem beliebigen Inhalt. Das Script wird beim Upgrade des Moduls automatisch am Ende ausgeführt.
=== Datenbankbasierte hochschulspezifische Laderegeln ===
Eine Laderoutine gliedert sich in die Schritte
#Unload: Entladen der CSV Dateien aus dem jew. Vorsystem
#Load: Upload der CSV Dateien
#Trans: Transformation der Daten
#Aggr: Aggregation der Daten
#Test: Test der Daten
#System: Standdatum bei Erfolg aktualisieren
Es ist möglich über sog. "Preparation"- oder "Finalize"-[[Kernmodul_Shellscripte#Hochschulspezifische_Transformationen_im_ETL-Prozess|Scripte]] die Laderoutine am Ende von LOAD bzw. TRANS anzupassen. Dieses Verfahren ist weiterhin möglich, ist aber bzgl. Clustering und Schreibzugriff recht unflexibel.

Es ist auch möglich im Browser hochschulspezifische Scripte am Ende des jeweiligen Schrittes einer Laderoutine anzulegen. Dies funktioniert so: Die Laderoutine führt zunächst den allgemeinen, von uns vorgegebenen Ladeschritt aus. Wenn dann eine Repository-Variable mit einem gewissen Namensschema existiert, wird sie ausgeführt. Das Namensschema lautet
<source lang="xml">
<<Kürzel der Komponente>>_<<Ladeschritt>>_CUSTOM
</source>.
* Bei Hauptladeroutinen ist dies
*# Laden: '''Kürzel der Komponente'''_load_CUSTOM, z. B. sos_load_CUSTOM
*# Transformation: '''Kürzel der Komponente'''_trans_CUSTOM, z. B. sos_trans_CUSTOM
*# Aggregation: '''Kürzel der Komponente'''_aggr_CUSTOM, z. B. sos_aggr_CUSTOM
* Bei Unterladeroutinen ist dies '''Kürzel der Komponente'''_'''ID des Ladeschritts'''_CUSTOM, also z. B. cob_trans_fin_busa_CUSTOM für die Unterladeroutine "Lade Buchungen aus FIN"

Um eine Variable neu einzurichten:
* Gehen Sie in den BI-Standardberichten auf Administration/Hochschul-Repository.
* Wählen Sie das jeweilige Sachgebiet und schicken Sie das Formular ab.
* Klicken Sie bei einer Beispielzeile auf '''Bearbeiten'''.
* Im neuen Fenster klicken Sie oben ganz rechts auf das Symbol '''Datensatz kopieren'''.
* Definieren Sie die Variable z. B.
** als Variablenname die ID z. B.: fin_load_CUSTOM
** Art der Variable: ein für Sie sprechender Schlüssel mit Modulkürzel, z. B. "fin_Laderegel"
** als Inhalt der Variable die gewünschten Befehle, z. B.
<source lang="sql">
update fin_buch_neu set ch110_institut=buchungsab_fb where length(buchungsab_fb)=5;
</source>
** aktiv=1
** gültig seit 1.1.1900
** gültig bis 1.1.3000
* Klicken Sie oben rechts auf das Häkchen-Symbol für '''Datensatz einfügen'''.
* Schließen Sie das Fenster.

Analog können Sie auch die [[Kernmodul_Komponentenverwaltung#Dateibasierte_hochschulspezifische_Anpassung|customize]]-Regeln" ins Repository verlagern. Hier heißt die Variable z.B. fin_install_CUSTOM.

== Entfernen eines Moduls ==
Wenn Sie ein Modul nicht mehr benötigen, starten Sie das Script 
$SUPERX_DIR/db/module/-Modulname-/-Modulname-_modul_entfernen.x. 
Dieses Script löscht alle Tabellen, Prozeduren und Abfragen aus der Datenbank, und löscht auch die Einträge im Themenbaum. Danach können Sie den Pfad $SUPERX_DIR/db/module/-Modulname-löschen.
Wenn Sie nur die Inhalte der Daten- und Hilfstabellen des Moduls löschen wollen (z.B. aus Datenschutzgründen), ohne das ganze Modul zu deinstallieren, können Sie dies mit folgendem Befehl tun:
DOSQL $SUPERX_DIR/db/module/-Modulname-/-Modulname-_purge_pg.sql (für Postgres) 
bzw. 
DOSQL $SUPERX_DIR/db/module/-Modulname-/-Modulname-_purge_ids.sql (für Informix)

Datei:SuperX ETL Manager Aktueller Lauf.png

2026-07-13T06:42:38Z

Andrek:

Datei:SuperX ETL Manager Aktionsbuttons.png

2026-07-13T06:42:23Z

Andrek:

Datei:SuperX ETL Manager Uebersicht.png

2026-07-13T06:41:49Z

Andrek:

Kernmodul Komponentenverwaltung

2026-07-13T06:37:11Z

Andrek:

Die Komponentenverwaltung im Kernmodul kann je nach Aufgabe über die Browseroberfläche oder über Shell-Skripte erfolgen.

Bisher wurden die Installation, Deinstallation, Aktualisierung und das Upgrade von Modulen überwiegend über Skripte in der Shell durchgeführt. Ab Kernmodul 6.0 steht zusätzlich eine Komponentenverwaltung über die Browseroberfläche zur Verfügung. Diese Browseroberfläche wird im Folgenden als SuperX ETL Manager beschrieben.

Der SuperX ETL Manager ist vor allem für die Ausführung und Überwachung von ETL-Prozessen sowie für Modul-Upgrades vorgesehen. Die Installation und Deinstallation von Modulen stehen dort bisher nicht zur Verfügung und werden weiterhin über die Shell-Skripte durchgeführt.

Der folgende Artikel ist daher in zwei Bereiche gegliedert: Zuerst wird die Nutzung des SuperX ETL Managers beschrieben. Anschließend folgt die bisherige Dokumentation zur Installation und Verwaltung von Modulen mit Skripten.

= Komponentenverwaltung im Browser: SuperX ETL Manager =
Der SuperX ETL Manager dient dazu, ETL-Prozesse der installierten SuperX-Module über die Weboberfläche auszuführen und zu überwachen. Er bietet eine zentrale Übersicht über installierte Module, verfügbare Aktionen, Versionsinformationen, Datenquellen, den aktuellen Lauf sowie technische Zusatzinformationen für die Fehlersuche.

Der Schwerpunkt der Oberfläche liegt auf dem täglichen Betrieb: Anwenderinnen und Anwender können Laderoutinen starten, den aktuellen Stand eines Laufs verfolgen und bei Bedarf die Log-Ausgabe einsehen. Technische Detail- und Diagnoseinformationen stehen ebenfalls zur Verfügung, sind aber vor allem für Administratorinnen und Administratoren oder den Support gedacht.

[[Datei:SuperX_ETL_Manager_Uebersicht.png|mini|zentriert|Platzhalter: Gesamtübersicht des SuperX ETL Managers mit Modulübersicht, Filterbereich, Aktionsbuttons und aktuellem Lauf.]]

== Aufbau der Oberfläche ==

Die Oberfläche besteht im Wesentlichen aus folgenden Bereichen:

* Filterbereich
* Modulübersicht
* Aktionsbuttons pro Modul
* Bereich „Aktueller Lauf“
* Log-Ausgabe
* Details-Bereich
* Diagnose-Bereich

Über den Filterbereich kann die angezeigte Modulliste eingeschränkt werden. Die Modulübersicht zeigt die wichtigsten Informationen zu den vorhandenen Modulen. Über die Aktionsbuttons können ETL-Prozesse gestartet werden. Der Bereich „Aktueller Lauf“ zeigt den zuletzt gestarteten oder aktuell laufenden Prozess an.

Die Bereiche „Details“ und „Diagnose“ liefern zusätzliche technische Informationen. Sie sind hilfreich für Supportfälle, aber für die normale Bedienung nicht zwingend erforderlich.

== Modulübersicht ==

Die Modulübersicht zeigt die installierten bzw. erkannten Module mit ihren wichtigsten Eigenschaften.

{| class="wikitable"
! Spalte
! Bedeutung
|-
| Modul
| Zeigt den Namen und das technische Kürzel des Moduls, zum Beispiel „Administration“ mit dem Kürzel „kern“ oder „Kennzahlen“ mit dem Kürzel „kenn“.
|-
| Status
| Zeigt, ob das Modul installiert ist.
|-
| Versionen
| Zeigt die installierte Version und die verfügbare Version des Moduls.
|-
| Letztes Update
| Zeigt den Zeitpunkt des letzten bekannten Updates.
|-
| Datenquelle
| Zeigt, aus welcher Datenquelle das Modul seine Daten bezieht oder auf welcher Datenbasis der ETL-Prozess arbeitet.
|-
| DB-Verbindung
| Zeigt, ob die Verbindung zur Datenbank bzw. Datenquelle aktuell erreichbar ist.
|-
| Aktionen
| Zeigt die verfügbaren Aktionen für das jeweilige Modul.
|}

=== Versionen ===

In der Spalte „Versionen“ werden zwei Werte angezeigt:

* installierte Version
* verfügbare Version

Die installierte Version beschreibt den Stand, der aktuell in der Datenbank installiert ist. Die verfügbare Version beschreibt den ausgelieferten Stand des Moduls, der in der Installation vorliegt.

Wenn die verfügbare Version höher ist als die installierte Version, sollte in der Regel ein Upgrade des Moduls durchgeführt werden. Dadurch werden die Datenstrukturen des Moduls auf den ausgelieferten Stand aktualisiert.

=== Datenquelle ===

Die Datenquelle gibt an, aus welchem System ein Modul seine Daten bezieht oder auf welcher Datenbasis es arbeitet.

SuperX ist ein Data Warehouse. Viele Module übernehmen Daten aus externen vorsystemen. Beispiele für solche Datenquellen sind:

* cob für Kostenrechnung
* mbs für Finanzrechnung, Inventar oder Gebäude/Räume/Flächen
* sva für Personal- und Stelleninformationen
* hisinone bei entsprechend angebundenen Modulen

Daneben gibt es Module, die auf bereits in SuperX vorhandene Daten zurückgreifen. In solchen Fällen wird als Datenquelle „SuperX“ angezeigt. Das betrifft vor allem Module, die modulübergreifend, auswertungsorientiert oder spezialisiert auf vorhandene SuperX-Daten zugreifen.

Beispiele hierfür können sein:

* kenn für Kennzahlen
* man für Managementberichte
* erfolg für Studienverlauf bzw. Erfolgsbetrachtungen
* gang für Studiengänge

Die Datenquelle „SuperX“ bedeutet also nicht, dass keine Daten verarbeitet werden. Sie zeigt an, dass die Verarbeitung auf Daten basiert, die bereits im SuperX-System vorhanden sind.

== Aktionen ausführen ==

Die verfügbaren Aktionen hängen vom jeweiligen Modul ab. Nicht jedes Modul unterstützt alle Aktionen. Wenn eine Aktion nicht verfügbar ist, wird der entsprechende Button nicht angezeigt oder ist nicht aktiv.

[[Datei:SuperX_ETL_Manager_Aktionsbuttons.png|mini|zentriert|Platzhalter: Modulzeile mit den Aktionsbuttons Unload, Update, Unload & Update und Upgrade.]]

=== Unload ===

Die Aktion „Unload“ entlädt Daten aus einem angebundenen Vorsystem, sofern für das Modul ein Vorsystem angebunden ist.

Der Unload dient dazu, Daten aus der jeweiligen Datenquelle bereitzustellen, damit sie anschließend in SuperX verarbeitet werden können. Je nach Modul und Einrichtung kann der Unload auch dazu dienen, Daten für eine weitere Verarbeitung oder Übertragung bereitzustellen.

=== Update ===

Die Aktion „Update“ lädt vorhandene Rohdaten in SuperX ein und führt die Hauptladeroutine des Moduls aus.

Dies ist in vielen Fällen die wichtigste Aktion für den täglichen Betrieb. Beim Update werden die vorhandenen Rohdaten verarbeitet und die zugehörigen SuperX-Tabellen aktualisiert.

=== Unload & Update ===

Die Aktion „Unload & Update“ führt zuerst den Unload und anschließend das Update aus.

Diese Aktion ist sinnvoll, wenn neue Daten aus einem angebundenen Vorsystem entladen und direkt anschließend in SuperX verarbeitet werden sollen.

=== Upgrade ===

Die Aktion „Upgrade“ führt eine Modulaktualisierung durch. Dabei werden die Datenstrukturen des Moduls auf den ausgelieferten Stand gebracht.

Ein Upgrade sollte ausgeführt werden, wenn eine neue verfügbare Version angezeigt wird oder wenn dies im Rahmen eines Modulupdates erforderlich ist.

== Sonderfall Kennzahlen-Modul ==

Beim Kennzahlen-Modul „kenn“ ist die Verarbeitung etwas anders als bei typischen Modulen mit externem Vorsystem.

Die Datenquelle ist hier in der Regel „SuperX“. Das bedeutet, dass die Kennzahlen nicht primär aus einem externen Fremdsystem entladen werden. Stattdessen basiert die Verarbeitung auf Daten, die bereits in SuperX vorhanden sind.

Für den täglichen Betrieb ist beim Kennzahlen-Modul daher häufig vor allem die Aktion „Update“ relevant. Dabei werden die Kennzahlen auf Basis der vorhandenen SuperX-Daten neu berechnet bzw. aktualisiert.

Die Aktion „Unload“ kann beim Kennzahlen-Modul eine andere Bedeutung haben als bei klassischen Vorsystem-Modulen. Sie kann dazu dienen, Kennzahlen für ein anderes System bereitzustellen, zum Beispiel:

* für ein hochschulübergreifendes SuperX
* für Vergleichssysteme
* für landesweite Auswertungen oder Berichtssysteme

Die kombinierte Aktion „Unload & Update“ ist beim Kennzahlen-Modul daher nicht immer die wichtigste Aktion. In vielen Installationen wird das Update gezielt über die Oberfläche ausgeführt, während Export- oder Übertragungsprozesse über automatische Abläufe wie Cronjobs gesteuert werden können.

== Aktueller Lauf ==

Der Bereich „Aktueller Lauf“ zeigt Informationen zum zuletzt gestarteten oder aktuell laufenden ETL-Prozess.

Typische Informationen sind:

* JobExecutionId
* Name des gestarteten Jobs
* Status
* Fortschritt
* Anzahl der ausgeführten Schritte
* Log-Ausgabe

[[Datei:SuperX_ETL_Manager_Aktueller_Lauf.png|mini|zentriert|Platzhalter: Bereich „Aktueller Lauf“ mit JobExecutionId, Status, Fortschritt und Log-Ausgabe.]]

=== Status ===

Der Status zeigt den aktuellen Zustand des Laufs. Häufige Statuswerte sind:

{| class="wikitable"
! Status
! Bedeutung
|-
| STARTING
| Der Lauf wird gestartet.
|-
| STARTED
| Der Lauf wurde gestartet und wird ausgeführt.
|-
| COMPLETED
| Der Lauf wurde erfolgreich abgeschlossen.
|-
| FAILED
| Der Lauf ist mit einem Fehler abgebrochen.
|-
| STOPPED
| Der Lauf wurde gestoppt.
|}

=== Fortschritt ===

Der Fortschritt zeigt, wie viele Prozessschritte bereits abgearbeitet wurden. Er ist als technischer bzw. prozessbezogener Fortschritt zu verstehen.

Wichtig ist: Der Fortschrittswert ist keine genaue Zeitprognose.

Ein Lauf kann schnell auf eine hohe Prozentzahl springen und dort längere Zeit stehen bleiben, wenn ein einzelner Verarbeitungsschritt besonders lange dauert. Umgekehrt können viele kleine Schritte sehr schnell nacheinander abgeschlossen werden. Die Prozentanzeige beschreibt daher den Abarbeitungsstand der Prozessschritte, nicht die tatsächlich vergangene oder verbleibende Zeit.

Beispiel:

Ein Lauf kann bereits 80 % anzeigen, obwohl noch ein größerer Verarbeitungsschritt aussteht. Ebenso kann ein Lauf am Anfang längere Zeit bei einer niedrigen Prozentzahl stehen bleiben, wenn ein früher Prozessschritt besonders umfangreich ist.

== Log-Ausgabe ==

Die Log-Ausgabe zeigt technische Informationen zum ausgeführten ETL-Prozess. Sie kann helfen, den Ablauf nachzuvollziehen und bei Problemen erste Hinweise zu erhalten.

Die Log-Ausgabe ist vor allem für Supportfälle hilfreich. Für eine tiefergehende Fehleranalyse sind in der Regel administrative Kenntnisse erforderlich. Je nach Fehler müssen zusätzlich Serverlogs, Datenbankinhalte, Moduldateien oder Systemkonfigurationen geprüft werden.

Wenn die Log-Ausgabe nicht sofort erscheint, kann sie über „Log laden“ erneut abgefragt werden. Gerade bei umfangreichen Läufen kann es vorkommen, dass die Log-Ausgabe erst kurze Zeit nach Abschluss vollständig verfügbar ist.

== Typische Nutzungsszenarien ==

=== Bereits vorhandene Rohdaten verarbeiten ===

Wenn die Rohdaten bereits vorhanden sind und lediglich erneut verarbeitet werden sollen, wird in der Regel die Aktion „Update“ verwendet.

Beispiel:

* Rohdaten liegen bereits im System vor
* Berechnungen oder Aggregationen sollen neu ausgeführt werden
* die SuperX-Tabellen des Moduls sollen aktualisiert werden

Geeignete Aktion:

<pre>
Update
</pre>

=== Neue Daten aus einem Vorsystem übernehmen und verarbeiten ===

Wenn neue Daten aus einem externen Vorsystem übernommen und anschließend verarbeitet werden sollen, kann die Aktion „Unload & Update“ verwendet werden.

Dabei werden zunächst die Daten aus dem Vorsystem entladen. Anschließend werden die Daten durch das Update in SuperX verarbeitet.

Geeignete Aktion:

<pre>
Unload & Update
</pre>

=== Nur Daten aus einem Vorsystem entladen ===

Wenn Daten aus einem Vorsystem entladen werden sollen, ohne direkt anschließend die Laderoutine auszuführen, kann die Aktion „Unload“ verwendet werden.

Geeignete Aktion:

<pre>
Unload
</pre>

=== Modul auf den ausgelieferten Stand aktualisieren ===

Wenn eine neue verfügbare Version angezeigt wird, sollte ein Upgrade geprüft bzw. durchgeführt werden.

Geeignete Aktion:

<pre>
Upgrade
</pre>

=== Kennzahlen innerhalb von SuperX aktualisieren ===

Beim Kennzahlen-Modul „kenn“ werden die Daten in der Regel aus SuperX selbst bezogen. Wenn die Kennzahlen neu berechnet oder aktualisiert werden sollen, ist häufig die Aktion „Update“ die passende Aktion.

Geeignete Aktion:

<pre>
Update
</pre>

=== Kennzahlen für ein anderes System bereitstellen ===

Wenn Kennzahlen für ein anderes System bereitgestellt werden sollen, kann beim Kennzahlen-Modul die Aktion „Unload“ relevant sein.

Dies kann zum Beispiel für hochschulübergreifende Auswertungen, Vergleichssysteme oder landesweite Berichtssysteme genutzt werden.

Geeignete Aktion:

<pre>
Unload
</pre>

== Hinweise zur Nutzung ==

Bei der Nutzung des ETL Managers sollten folgende Punkte beachtet werden:

* Ein laufender Prozess sollte nicht unnötig mehrfach parallel gestartet werden.
* Nach einem Lauf kann die Modulübersicht über „Aktualisieren“ neu geladen werden.
* Die Prozentanzeige ist kein Zeitindikator, sondern beschreibt den Fortschritt der Prozessschritte.
* Bei Fehlern sollte zuerst der Status und anschließend die Log-Ausgabe geprüft werden.
* Für tiefergehende Fehleranalysen sollten Administratorinnen und Administratoren oder technische Ansprechpartner einbezogen werden.
* Bei neuen verfügbaren Modulversionen sollte geprüft werden, ob ein Upgrade auszuführen ist.

== Details-Bereich ==

Über den Button „Details“ können zusätzliche technische Informationen zu einem Modul angezeigt werden.

Der Details-Bereich ist vor allem für fortgeschrittene Benutzerinnen und Benutzer, Administratorinnen und Administratoren oder den Support gedacht. Er kann unter anderem folgende Informationen enthalten:

* technische Modulkennung
* Systeminfo-ID
* technische Jobnamen
* verfügbare Jobs
* Rohdaten der Schnittstelle
* zusätzliche technische Moduldetails

Für den normalen Betrieb ist der Details-Bereich meist nicht erforderlich. Er ist vor allem dann hilfreich, wenn bei Rückfragen oder Supportfällen genaue technische Informationen benötigt werden.

== Diagnose-Bereich ==

Der Diagnose-Bereich ist eine technische Hilfsfunktion zur Prüfung der ETL-Manager-Installation. Er ist global angeordnet und nicht auf ein einzelnes Modul beschränkt.

Die Diagnose führt keine Reparaturen automatisch aus. Sie zeigt technische Informationen, mögliche Auffälligkeiten und Hinweise an. Zusätzlich können SQL- oder Shell-Hinweise angezeigt werden, die bei Bedarf von Administratorinnen und Administratoren kopiert und manuell ausgeführt werden können.

Der Diagnose-Bereich kann unter anderem folgende Informationen enthalten:

* Erreichbarkeit der REST-Schnittstellen
* Webapp-, Tomcat- und Java-Informationen
* Pfade und Dateisysteminformationen
* Festplattenspeicher
* Datenbankinformationen
* Prüfung der Log-Tabelle
* Versionsquellen
* bekannte Fehlerbilder
* kopierbare SQL- und Shell-Hinweise

Der Diagnose-Bereich ist vor allem für Administratorinnen und Administratoren oder technische Ansprechpartner gedacht. Für normale Anwenderinnen und Anwender ist er in der Regel nur dann relevant, wenn ein Fehler auftritt oder technische Informationen weitergegeben werden sollen.

== Administratorhinweise ==

Dieser Abschnitt enthält ergänzende technische Hinweise. Er richtet sich vor allem an Administratorinnen und Administratoren sowie an den technischen Support.

=== Herkunft der Versionsinformationen ===

Die Oberfläche zeigt eine installierte und eine verfügbare Version an.

Die installierte Version beschreibt den Stand, der in der Datenbank installiert ist. Falls die REST-Schnittstelle keinen Wert liefert, kann die Version aus der Tabelle <code>db_version</code> gelesen werden.

Die verfügbare Version beschreibt den ausgelieferten Stand im Dateisystem. Sie kann aus der Modul-XML-Datei gelesen werden. Für normale Module liegt diese Datei typischerweise unter:

<pre>
WEB-INF/conf/edustore/db/module/<modul>/conf/<modul>.xml
</pre>

Für das Kernmodul gilt ein Sonderfall. Die Modul-XML liegt unter:

<pre>
WEB-INF/conf/edustore/db/install/conf/kern.xml
</pre>

Zusätzlich kann eine Datei <code>VERSION</code> im jeweiligen Modulverzeichnis als Fallback verwendet werden.

=== Log-Tabelle ===

Die Log-Ausgabe des ETL Managers verwendet eine Datenbanktabelle für die Joblogs. Wenn diese Tabelle fehlt oder unvollständig ist, kann die Log-Ausgabe fehlschlagen.

Eine mögliche Struktur der Tabelle ist:

<pre>
CREATE TABLE IF NOT EXISTS job_log
(
job_instance_id bigint NOT NULL,
log text,
status text
);

CREATE UNIQUE INDEX IF NOT EXISTS ix_job_log1
ON public.job_log USING btree (job_instance_id);
</pre>

Diese SQL-Anweisungen sollten nicht automatisch durch die Oberfläche ausgeführt werden. Sie dienen als Hinweis für Administratorinnen und Administratoren und müssen bei Bedarf manuell geprüft und ausgeführt werden.

=== Typische technische Fehlerbilder ===

{| class="wikitable"
! Fehlerbild
! Mögliche Ursache
|-
| <code>/jobLog/{id}</code> liefert HTTP 500
| Die Tabelle <code>job_log</code> fehlt, ist unvollständig oder der Logeintrag ist noch nicht verfügbar.
|-
| <code>/job/list/{modul}</code> liefert HTTP 500
| Moduldateien fehlen, Pfade stimmen nicht oder die Webapp verwendet nicht den erwarteten Dateistand.
|-
| REST-Endpunkt liefert HTTP 404
| Der Context-Pfad, die Webapp, der Port oder ein Tunnel zeigt möglicherweise nicht auf die erwartete Anwendung.
|-
| Log erscheint erst nach erneutem Laden
| Der ETL-Lauf ist abgeschlossen, aber der Logeintrag war beim ersten Abruf noch nicht vollständig verfügbar.
|}

== Zusammenfassung ==

Der SuperX ETL Manager stellt eine zentrale Oberfläche zur Ausführung und Überwachung von ETL-Prozessen bereit. Für den täglichen Betrieb stehen vor allem die Aktionen „Unload“, „Update“, „Unload & Update“ und „Upgrade“ im Vordergrund.

Die Modulübersicht zeigt den Installationsstatus, Versionsinformationen, Datenquellen und Datenbankverbindungen. Der Bereich „Aktueller Lauf“ informiert über den Fortschritt eines gestarteten Prozesses. Die Log-Ausgabe liefert technische Zusatzinformationen und kann bei der Fehleranalyse helfen.

Details und Diagnose ergänzen die Oberfläche um technische Informationen für Support- und Administrationsfälle. Sie unterstützen bei der Analyse, führen aber keine automatischen Reparaturen aus.

= Installation und Verwaltung in der Shell mit Skripten =

== Installation von Modulen ==
Das Kernmodul enthält außer Administrationsabfragen und Tabellen keinerlei Inhalte. Die Inhalte werden in Form von Modulen hinzugefügt. Dazu gibt es vorgefertigte [[Kernmodul_Shellscripte#Modulverwaltung|Installationsscripte]].

=== Architektur von SuperX-Modulen ===
Die folgende Abbildung zeigt die Architektur von Modulen ab Beispiel vom HISCOB-Modul:

{| class="wikitable"
|-
!
!
|-
| Ein Modul besteht auf Datenbankseite aus Abfragen, Hilfstabellen, Datentabellen und Schlüsseltabellen (sowie Prozeduren).
Auf Webserver-Seite können auch XSL-Stylesheets vorhanden sein.
| [[Bild:modularchitektur_cob.png|417x307px]]
|}
Die Abbildung zeigt, dass ein Modul eigene Komponenten nutzt, aber auch auf Teile des Kernmoduls zugreift, z.B. das Orgranigramm - dies macht SuperX zu einem integrierten System. Neben dem Organigramm sind alle anderen Komponenten des Kernmoduls natürlich betroffen, z.B. Themenbaum, Userrechte.
Die Ordnerstruktur eines Moduls spiegelt die Komponenten des Systems wieder. Es gibt je ein Verzeichnis für datentabellen, schluesseltabellen und hilfstabellen.
Die Installation eines Moduls ist in der Dokumentation des jeweiligen Moduls näher beschrieben. Module, die auf dem Kernmodul 2.1 oder höher basieren, haben einen einheitlichen Aufbau.

=== Modulscripte im Kernmodul ===
Seit Version 2.1 werden die Datenbankschemata und Scripte der Module in einem einheitlichen Format zusammengestellt und in einer Datei $SUPERX_DIR/db/module/$MODULNAME/conf/$MODULNAME.xml gespeichert. Das XML-Format hat den Vorteil, dass die Scripte dynamisch für Postgres und Informix erzeugt werden können, und dass die Scripte vereinheitlicht werden. Aus dieser Datei werden die Scripte erzeugt, die das Modul jeweils für Postgres und Informix installieren / updaten /aktualisieren / überprüfen und entfernen. Die folgende Abbildung zeigt das Vorgehen:

{| class="wikitable"
|-
!
!
|-
| Aus der xml-Datei werden die jeweiligen Scripte für die Installation, den Update, die Extraktions-, Transformations- und Ladescripte (ETL) und die Deinstallation erzeugt.
| [[Bild:modulscripte_erzeugen.png|417x371px]]
|}

Die Modul-Scripte liegen als Shellscripte im Verzeichnis $SUPERX_DIR/db/bin, und sind an [[Kernmodul_Shellscripte#Modulverwaltung|anderer Stelle]] im Detail erläutert.

{| class="wikitable"
|-
!
!
|-
| module_install.x -name- -pfad-
z.B.:
module_install.x sos $SOS_PFAD
| Installiert ein Modul, d.h. erzeugt die Tabellen, Views, Funktionen und Abfragen. Die Abfragen werden in den Themenbaum eingehängt.
|-
| module_etl.x -name- -pfad-
z.B.:
module_etl.x sos $SOS_PFAD
| Aktualisiert das Modul, d.h. lädt die Rohdaten, Transformiert sie, und aggregiert die Hilfstabellen. Fehler werden in eine Log-Datei geschrieben, diese kann dann per Mail an einen Admin versandt werden. Wenn das Script erfolgreich durchläuft, wird die Tabelle systeminfo aktualisiert. 
Das Script wird nicht direkt als Cronjob aufgerufen, sondern von einem Shellscript, das die Umgebungsvariablen und Parameter setzt, z.B. cob_update.x.
|-
| module_drop.x -name- -pfad-
z.B.:
module_ drop.x sos $SOS_PFAD
| Entfernt das Modul bzw. die Tabellen, Views, Funktionen und Abfragen.
|-
| module_scripts_create.x -name- -pfad- -Datenbanksystem(optional, INFORMIX, POSTGRES)- -Versionsnr.-
| Erzeugt via XSL-Transformation die jeweiligen Scripte, die in den obigen Scripten aufgerufen werden, z.B. bau_install_ids.sql für das Installationsscript des Baumoduls beim Informix Dynamic Server.
|}

Neben den operativen Scripten erzeugt module_scripts_create.x auch html-Dateien zur Dokumentation eines Moduls in
$SUPERX_DIR/db/module/-Modulname-/conf/-Modulname-.html
(auch als rtf-Datei zu Einbindung in Modul-Dokumentationen) sowie zur Schnittstelle in
$SUPERX_DIR/db/module/-Modulname-/rohdaten/-Modulname-_unload.html
Darüber hinaus werden auch DBForms-Formulare erzeugt.

=== Installation eines Moduls: Allgemeines Vorgehen ===
Das Vorgehen bei der Installation eines Moduls ist standardisiert. Im folgenden eine Kurzbeschreibung, weiter unten finden Sie das Vorgehen am Beispiel des ZUL-Moduls im Detail.
* Entpacken Sie das Modul in $SUPERX_DIR
* Erweiterung der Umgebung in der Datei $SUPERX_DIR/db/bin/SQL_ENV: fügen Sie den Inhalt der jew. Beispieldatei SQL_ENV_-Modulname-.sam in der SQL_ENV an, wenn noch nicht vorhanden, und ändern Sie ggf. Email-Adressen für log- und Fehlermails.
* Entladen der Rohdaten; auch hier müssen vorher Umgebungsvariablen zum Vorsystem angepasst werden 
(Datei $-Modulname-_LOAD_PFAD/-Modulname-_ENV), hier liegt ebenfalls eine *.sam-Datei vor
* Kopieren der Rohdaten nach -Modulpfad-/rohdaten. Neuere SuperX-Module haben dafür vorgefertigte Scripte mit dem Namen -Modulname-_copy.x (z.B. zul_copy.x)
* Installieren Sie das Modul mit -Modulname-_erzeugen.x, z.B. mit zul_modul_erzeugen.x
* Wenn die Installation erfolgreich war, können Sie das Modul aktualisieren mit 
-Modulname-_update.x (ggf. mit Parametern) 
z.B. mit
zul__update.x
d.h. die ETL-Prozesse werden gestartet (s.u.).
* Wenn das Modul erfolgreich aktualisiert ist, wird eine Prüfprozedur gestartet, die die Daten plausibilisiert. Fehler und Warnungen finden Sie in der Datei $-Modulname-_ERRORDAT.
* Starten Sie Tomcat neu. Wenn Tomcat auf einem separaten Server installiert ist, müssen Sie vorher die Datei $SUPERX_DIR/webserver/tomcat/webapps/superx/WEB-INF/dbforms-config.xml dorthin übertragen.
* Schritt 7 wird bei jedem SuperX-Update wiederholt. Nun muss der Entladerhythmus geplant werden, und die Cronjobs werden eingerichtet. Es gibt eine Musterdatei $SUPERX_DIR/db/module/-MODULNAME-/-MODUL-_update_cron.x.sam , benennen sie diese um nach -MODUL-_update_cron.x und fügen Sie das Script in die crontab ein.

==== Allgemeines zum Laden ====
Zunächst müssen die Rohdaten aus dem Vorsystem entladen werden.
Für das Entladen gibt es ferner zwei Modi: Das "Pull"-Verfahren und das "Push"-Verfahren.
* Beim '''"Pull"-'''Verfahren wird einer Benutzerkennung auf dem SuperX-Rechner Zugriffsrecht auf die SOSPOS-Datenbank gegeben, und die Daten werden via TCP/IP aus dem Basissystem entladen. Bei APP / HISinOne als Quellsystem ist "Pull" das Standardvorgehen.
* Beim '''"Push"-'''Verfahren werden die Entladescripte auf den SOSPOS-Rechner kopiert und dort von einer Benutzerkennung auf dem SOSPOS-Rechner ausgeführt. Die Rohdaten müssen dann auf den SuperX-Rechner kopiert werden. Dieses Verfahren klappt bei Informix unter Unix problemlos, bei Entladen aus Postgres müsste das komplette SuperX-Kernmodul installiert werden.
Am einfachsten ist immer das "Pull"-Verfahren, das mit fast allen Quellsystemen funktioniert und wenig Konfiguration auf dem Quellsystem erfordert. Aufgrund von Sicherheitsvorkehrungen oder Netz-Infrastrukturen wählen aber viele Hochschulen das "Push"-Verfahren. Da derzeit Informix /Unix die gängigste Plattform an Hochschulen ist, ist dies auch kein Problem.

==== Einrichtung der Entladescripte ====
Im Push-Verfahren btw. unter SuperX können Sie mitgelieferte Shellscripte nutzen. Das folgende Beispiel des ZUL-Moduls zeigt das Vorgehen:
Die Entladescripte liegen im Verzeichnis $SUPERX_DIR/db/module/zul/rohdaten und lauten je nach Systemversion:
zul_unload.x

Die Scripte laufen nur, wenn die entsprechenden Umgebungsvariablen in der Datei ZUL_ENV (im gleichen Verzeichnis, ein Muster liegt vor in ZUL_ENV.sam) korrekt gesetzt sind, benennen Sie die Musterdatei um nach ZUL_ENV und tragen die richtigen Umgebungsvariablen ein, z.B. den Pfad für $INFORMIXDIR.
'''ZUL_ENV Die Umgebung für Entladescripte aus ZUL-GX(Auszug)'''
##Pfad für Entladedaten:
ZUL_PFAD=.; export ZUL_PFAD
##hier muss Unterverzeichnis unl existieren!

In der ZUL_ENV müssen außerdem folgende Umgebungsvariablen gesetzt werden (defaults sind bereits vorbelegt, aber hier und da müssen Sie sicher ran):
{| class="wikitable"
|-
! Variable
! Erläuterung
|-
|
| '''Nur für Informix gelten:'''
|-
| INFORMIXDIR
| Home-Verzeichnis von Informix
|-
| INFORMIXSERVER
| Name des Informixservers
|-
| ONCONFIG
| Name der onconfig, wenn auf dem SOS-Rechner mehrere Informix-Instanzen laufen
|-
| CLIENT_LOCALE
| Sprachumgebung (wichtig fürs Entladen von Datumsformaten)
|-
| SERVER_LOCALE
| dito
|}

{| class="wikitable"
|-
! Variable
! Erläuterung
|-
|
| '''Nur für Postgres gelten:'''
|-
| PGDATESTYLE
| Datumsformat "German"
|-
| PGPORT
| Port vom Postgres-Server, standardmäßig 5432
|-
| PGHOST
| Hostname oder IP-Adresse vom Postgres-Server
|-
| PGUSER
| Benutzerkennung für Postgres-Server (nur Datenbank, nicht Betriebssystem)
|-
| PGPATH
| Installationsverzeichnis von Postgres, z.B. /usr/local/pgsql
|-
| DB_PROPERTIES
| Pfad zur db-zul.properties-Datei mit den Zugangsparametern für SOSPOS unter Postgres
|-
| LOGGING_PROPERTIES
| Pfad zur Steuerungsdatei mit den Parametern für das Logging beim Entladen, voreingestellt auf ./logging.properties. Normalerweise brauchen Sie hier nichts ändern, wenn beim Entladen Probleme auftauchen, kann man den Level von SEVERE auf INFO oder FINEST ändern, dann werden die konkreten SQLs geloggt. Aber Achtung: wenn keine Fehler mehr auftreten, müssen Sie den Level wieder auf SERVERE ändern, sonst kommen Schlüsselworte in die Logdatei zul_unload.err, die dann bei der Übernahme nach SuperX fälschlicherweise zu Fehlermeldungen führen.
|}
Unter Postgres muss für das "Pull"-Verfahren beim Entladen die Datenbankverbindung in der Datei db-zul.properties eingetragen werden (Muster für Postgres liegt bei in db-zul_pg.properties). Dazu laden Sie einmal die Datei ZUL_ENV mit den obigen Parameter, starten den SuperX-Propadmin (siehe Administrationshandbuch Kernmodul) und richten die Verbindung zum SOSPOS-Server ein. Das Kennwort wird verschlüsselt gespeichert. Danach sind die Entladescripte für Postgres ausführbar.
Hinweis: Anders als Informix hat Postgres hat eine eigene, vom Basissystem unabhängige Benutzerverwaltung. Daher brauchen Sie den User, den Sie zum Entladen aus Postgres nutzen, nicht auf dem SuperX- oder SOSPOS-Rechner auf Betriebssystem-Ebene einrichten. Sie können also z.B. auf dem SuperX-Rechner zum Entladen aus SOSPOS die Kennung sospos des Postgres- Rechners verwenden. Oder Sie richten in der SOSPOS -Datenbank den Benutzer SuperX ein und geben ihm Leserecht auf die Tabellen sowie das Recht, Tabellen und Stored Procedures anzulegen.

{| class="wikitable"
|-
! Variable
! Erläuterung
|-
|
| '''Für alle Platformen gelten folgende Variablen:'''
|-
| ERRORMAIL
| An wen solle eine Logmail verschickt werden, wenn das Entladen nicht geklappt hat? (nur Unix).
|-
| LOGMAIL
| An wen soll immer eine Logmail verschickt werden
|-
| MAILPROG
| Pfad zum ausführbaren Mailprogramm unter Unix, Vorbelegung ist "mail", manche Unixe haben aber auch "mutt" oder "mailx".
|-
|
| Wenn die Rohdaten beim Push-Verfahren nach dem Entladen vom ZUL-Rechner auf den SuperX-Rechner kopiert werden sollen, dann werden für das Script zul_copy.x folgende Umgebungsvariablen benötigt:
|-
| COPY_METHOD
| Programm, das die Dateien kopiert; rsync und scp sind wählbar.
|-
| REMOTE_DIR
| Verzeichnis, in das die Rohdaten auf dem SuperX-Rechner kopiert werden sollen, in der Regel ist dies "/home/superx/db/module/zul/rohdaten"
|-
| REMOTE_USER
| Der Unix-Username auf dem SuperX-Rechner, in der Regel "superx".
|-
| REMOTE_HOST
| Der Rechnername bzw. die IP-Nr. des SuperX-Rechners.
|}
Dann starten Sie das Script zul_unload.x. Wenn es gelaufen ist, müssten die Dateien im unl-Verzeichnis stehen. Prüfen Sie dann bitte, ob dort Dateien mit 0 bytes stehen. Die Logdatei heisst zul_unload.err.

===== Entladen unter Windows =====
Für das Entladen unter Windows gibt es Muster-Dateien im jew. Rohdaten-Verzeichnis, z.B. $SOS_PFAD/rohdaten/sos_unload.bat. Die Einrichtung geschieht dann in [[Kernmodul_Komponentenverwaltung#Java-Client_zum_Entladen_von_Quell-Datenbanken|Java]]. Ans Ende der Datei können Sie noch schreiben:
date /T >superx.datum
Dann wird auch die Datumsdatei geschrieben.

===== Dateitransfer beim Push-Verfahren =====
Wenn Sie das Verzeichnis nicht gemounted haben, müssen das Verzeichnis unl, die zul_unload.err und die superx.datum dann in das Verzeichnis $ZUL_LOAD_PFAD auf dem SuperX-Rechner kopiert werden, ein Script dafür liegt ebenfalls bei (zul_copy.x). Das Entladedatum wird danach in der Textdatei $ZUL_LOAD_PFAD/superx.datum gespeichert; wenn das Script einen Fehler findet, dann wird das vorherige Datum (in der Datei superx.datum.alt) gesetzt.

Für den Transfer der Rohdaten beim Push-Verfahren wird in SuperX die dateibasierte Schnittstelle genutzt. Unter UNIX läßt sich dieser Transfer vollends automatisieren, indem die Programme scp oder rsync auf der Basis des OpenSSH-Pakets genutzt werden. Beide setzen auf das ssh-Protokoll 2 auf und stellen somit einen verschlüsselten Dateitransfer sicher. Auch [[Kernmodul_Komponentenverwaltung#Einrichtung_von_SFTP|sftp]] ist möglich.
In den jeweiligen Modulen wird im Verzeichnis rohdaten eine Beispieldatei mit dem Namen -MODULNAME-_ENV.sam ausgeliefert, die Sie umbenennen können nach -MODULNAME-_ENV. Darin werden am Ende der Datei die Parameter zum Kopieren festgelegt, also die Userkennung REMOTE_USER, der Hostname REMOTE_HOST, und die Methode des Kopierens (COPY_METHOD) sowie die jeweiligen Zielpfade. Diese Umgebungsvariablen werden von dem jeweiligen Script -modulname-_copy.x benutzt.

===== Entfernen der Passworteingabe unter Unix =====
Damit die Passworteingabe unter Unix entfällt, muss man wie folgt vorgehen:
Loggen Sie sich zunächst testweise einmal ein. Wenn Sie z.B. vom COB-Server auf den SuperX-Server kopieren wollen, loggen Sie sich als user cob auf cobhost ein mit 
ssh superx@superxhost
Beim ersten Mal müssen Sie die Sicherheitsabfrage mit "yes" bestätigen.
Erzeugen Sie auf dem Quellrechner einen öffentlichen Schlüssel mittels

ssh-keygen -t ed25519 -C "cob@cobhost"

wobei man eine leere Passphrase vergibt. Der öffentliche Teil dieses Schlüssels (~/.ssh/id_ed25519.pub) muss auf dem Zielrechner in die Datei ~/.ssh/authorized_keys eingefügt werden, ggf. muss die Datei neu erzeugt werden.
Wenn z.B. auf dem COB-Server unter der Kennung cob ein Key wie folgt erzeugt wurde:

;Beispieleintrag eines Public Keys:

ssh-ed25519 AAAAC3N.[hier viele kryptische Zeichen]....4V cob@cobhost

Dann wird genau diese Zeile in der Datei /home/superx/.ssh/authorized_keys angefügt (die Datei kann mehrere PublicKeys enthalten, ein Eintrag pro Absatz).
Achten Sie auch auf Dateirechte: Die Verzeichnisse und Dateien sollten keine Schreibrechte für Gruppen haben. Im Zweifelsfall z.B. für den user superx:
chmod 700 /home/superx/.ssh
chmod 700 /home/superx/.ssh
chmod 600 /home/superx/.ssh/authorized_keys
Danach sollte z.B. der Login vom cobhost als user cob mit ssh superx@superxhost ohne Passworteingabe klappen. Wenn nicht, schalten Sie das Logging mit ssh -v superx@superxhost ein. Eine Möglichkeit ist, dass die PublicKey-Authentifizierung in der Konfigurationsdatei des SSHD (normal /etc/ssh/ssh_config) abgeschaltet ist. Weitere Diagnosen liefert die Datei /var/log/messages.
Sie können außerdem noch einschränken, von welchem Host die obige Authentifizierung ermöglicht wird. Dazu setzen Sie den Parameter "from=*.uni-xy.de" davor, z.B.

{| class="wikitable"
|-
!
!
|-
| Einschränkung "from" 
in authorized_keys
| from="*.uni-xy.de" ssh-rsa AAAAB3Nza…[hier viele kryptische
Zeichen]…pg6VkCc= cob@cobhost
|}

Wenn Sie die Kopiermethode scp benutzen, und die obige "authorized_keys"-Metohde mit PublicKey nicht nutzen wollen, können Sie auch mit Private Keys arbeiten (siehe SSH-Doku). Dazu können sie in der *_ENV-Datei in dem Parameter SCP_OPTS den Verweis auf den private Key setzen.
{| class="wikitable"
|-
!
!
|-
| SCP_OPTS in *_ENV: 
Beispiel COB_ENV
| SCP_OPTS="-p -B -i /home/cob/.ssh/superx_key"
export SCP_OPTS
|}

===== Entfernen der Passworteingabe unter Windows =====
Wenn Sie die ssh-Shell putty aus dem Installationspaket nutzen, haben Sie im Installationsordner auch die Anwendung "puttyGen.exe". Wenn Sie putty als reine Executable nutzen, laden Sie die Anwendung separat herunter. [http://winscp.net/download/puttygen.exe PuttyGen]
* Folgen Sie der Anleitung auf der Seite http://winscp.net/eng/docs/ui_puttygen, um den SSH2-DSA oder RSA Schlüssel zu erzeugen. Für den Schlüssel bitte kein Passwort vergeben, wenn Sie das Tool automatisiert nutzen.
* Den privaten Schlüssel geben Sie in Putty bzw. Winscp im Menü "Session" im Feld "Private Key File" an.
* Der Button "Save public key" ist nicht für OPENSSH unter Linux als Zielserver geeignet. Im folgenden Screenshot sehen Sie den markierten Bereich, den Sie kopieren müssen:
[[Bild:puttygen.png|413x402px]]
* Kopieren Sie Ihren Public Key, den Sie oben mit PuttyGen erzeugt haben, zur Datei "authorized_keys" und kopieren Sie diese in das Verzeichnis ~/.ssh/
* Im Profil unter Connection -> SSH -> Auth -> Credentials geben Sie den Pfad zum privaten Schlüssel in "Private key file" an.
* Bei erneutem Login mit Putty oder Winscp sollte die Passwortabfrage entfallen.

===== Einrichtung von SFTP (Server) =====
Beim Push-Verfahren wird, wenn mit scp oder rsync kopiert wird, eine Login-Shell vorausgesetzt. Wenn dies aus Sicherheitsgründen nicht gewünscht ist bzw. wg. Einsatz von Windows nicht möglich ist, können Sie auch sftp nutzen, dies wird in modernen ssh-Servern mitgeliefert und bietet ebenfalls verschlüsselten Datentransfer. Zur Einrichtung des Servers:
Der SSH-Dienst wird wie folgt konfiguriert (am Beispiel Ubuntu Linux 22.04 LTS) mit dem SFTP-Verzeichnis /home/sftp/-benutzername:

In der Datei /etc/ssh/sshd_config die Zeile auskommentieren:
#Subsystem sftp /usr/lib/openssh/sftp-server
und stattdessen:
Subsystem sftp internal-sftp
Match Group sftponly
ChrootDirectory /home/sftp/%u
ForceCommand internal-sftp
AllowTcpForwarding no

Danach starten Sie den SSH-Dienst neu:
service ssh restart

Dann legen Sie die Gruppe "sftponly" an:
groupadd sftponly
und dann den Unix-User an, und geben ihm die Gruppe "sftponly". Hier ein Script:
#!/bin/sh
SFTPUSERNAME=$1
mkdir -p /home/sftp/$SFTPUSERNAME
useradd -b /home/sftp -s /bin/false -G sftponly $SFTPUSERNAME
chown root:root /home/sftp/$SFTPUSERNAME
chmod 755 /home/sftp/$SFTPUSERNAME
mkdir -p /home/sftp/$SFTPUSERNAME/incoming
chown $SFTPUSERNAME:sftponly /home/sftp/$SFTPUSERNAME/incoming

Danach legen Sie mit
passwd $SFTPUSERNAME
ein Passwort fest.

Der User kann sich dann nicht mehr mit ssh einloggen, nur noch mit sftp, und landet beim Login in /home/$KENNUNG, in einem "chroot-Käfig", und der User kann mit SFTP in den Ordner "incoming" schreiben. Zum Testen geben Sie ein:
sftp $KENNUNG@-Host-

Wenn beim SFTP Login die Meldung kommt:
client_loop: send disconnect: Broken pipe
müssen Sie darauf achten dass das Home-Verzeichnis des Users nicht dem User gehört, sondern root.

Wenn der Login klappt, können Sie nach dem [[Kernmodul_Komponentenverwaltung#Entfernen_der_Passworteingabe_unter_Unix|oben]] beschriebenen Verfahren die Passworteingabe durch PublicKey-Authentifizierung ersetzen.

===== Einrichtung von SFTP =====
Für das Kopieren der Rohdaten können Sie im Kopierscript "-modulname-_copy.x" auch sftp-Kommandos nutzen. Sie müssen nur in der ENV-Datei die Variable
COPY_METHOD=sftp
setzen. Alle anderen Variablen und Mechanismen wie z.B. [[Kernmodul_Komponentenverwaltung#Entfernen_der_Passworteingabe_unter_Unix|Entfernen der Passworteingabe]] entsprechen denen von SCP / SSH (s.o.).
Spezielle Optionen fürs sftp können Sie in der Umgebungsvariable SFTP_OPTS setzen. Es kann z.B. sein, dass das Kopieren großer Dateien in einen Timeout läuft. Bei CSV bietet es sich an, die Dateien zu komprimieren, sie können also setzen:
SFTP_OPTS="-oCompression=yes"
export SFTP_OPTS
Danach wiederholen Sie das kenn_copy.x
Dies ist nur ein Beispiel. Weitere Optionen für SFTP entnehmen Sie der manpage.
Das Kopieren mit sftp klappt übrigens auch unter Windows z.B. mit dem Programm [http://winscp.net/eng/docs/lang:de winscp]. Dies wird im folgenden erläutert.

===== Einrichtung von SFTP unter Windows =====
Unter Windows ist das Standardprogramm für SFTP die Anwendung [http://winscp.net/eng/docs/lang:de winscp]. Sie können die Passworteingabe analog zu Putty [[Kernmodul_Komponentenverwaltung#Entfernen_der_Passworteingabe_unter_Windows|entfernen]]. Danach können Sie eine Session erzeugen:

[[Bild:winscp1.png|517x364px]]

Im Feld "Private key file" geben Sie den private key ein, den Sie [[Kernmodul_Komponentenverwaltung#Entfernen_der_Passworteingabe_unter_Windows|oben]] erzeugt haben. Klicken Sie dann auf "Save session", und geben Sie einen kurzen, sprechenden Namen ohne Leerzeichen oder Umlaute, z.B. "superx@vmmulti1"
Sie müssen nun die Verzeichnisse lokal und remote in der Winscp-Session speichern, im Menüpunkt "Directories":

[[Bild:winscp2.png|517x359px]]

Vergessen Sie auch hiernach nicht, die Session zu speichern.
Danach testen Sie einmal den Zugang. Wenn das klappt können Sie Winscp auch für die Kommandozeile automatisieren. Sie erzeugen zunächst eine Textdatei mit den Kommandos für Winscp, dies enthält auch die zu übertragenden Dateien. Der Aufbau der Datei ist wie folgt:
open -Sessionname-
# Upload the file to current working directory
put -Datei-
# Disconnect
close
# Exit WinSCP
exit

Die zu übertragenden Dateien sind in der Musterdatei des jew. Moduls in rohdaten/-Modulname-_sftp.txt aufgelistet, Sie müssen lediglich
* den "/" durch einen "\" ersetzen
* das Entladeprotokoll -Modulname-_unload.err und die Datumsdatei superx.datum hinzufügen
Hier ein Beispielscript fürs das Studierenden-Modul:
open superx@vmmulti1
# Change remote directory
# Upload the file to current working directory
put sos_unload.err
put superx.datum
put unl\konstanten.unl
put unl\sos_studenten.unl
put unl\sos_hzb.unl
put unl\sos_faecher.unl
put unl\sos_pord_to_stg.unl
put unl\sos_pruefungenext.unl
put unl\sos_pruefungen.unl
put unl\sos_lab_astat_attributes.unl
put unl\sos_stud_loe.unl
put unl\sos_faecher_ext.unl
put unl\sos_faecher_kontrolle.unl
put unl\sos_pruefungen_kontrolle.unl
put unl\sos_anschri.unl
put unl\sos_parstg.unl
put unl\sos_hsnr.unl
put unl\semester.unl
put unl\cif.unl
put unl\cifx.unl
put unl\k_pvers.unl
put unl\k_stg.unl
put unl\k_stgext.unl
put unl\k_abstgv.unl
put unl\sos_pord.unl
put unl\sos_dipl.unl
put unl\sos_minder.unl
put unl\sos_stud_d.unl
put unl\sos_pords.unl
put unl\sos_porg.unl
put unl\sos_labzuord.unl
put unl\sos_pnrzuord.unl
put unl\sos_gewichtungsvariante.unl
put unl\sos_gewichtungregel_filter.unl
put unl\sos_gewichtungregel.unl
put unl\personattribute.unl
put unl\personattributetype.unl
put unl\personattribute_value_list.unl
put unl\stu_update_prot.unl
put unl\exa_update_prot.unl
put unl\sos_accredited_ects.unl
put unl\sos_pord_orgeinheit.unl
# Disconnect
close
# Exit WinSCP
exit

Die Datei hat z.B. den Namen winscp_example_script.txt. Dann können Sie das Script aufrufen mit dem DOS-Kommando:
winscp /script=-Pfad zu-\winscp_example_script.txt

Hier ein Screenshot wie das dann aussieht:

[[Bild:winscp3.png|609x337px]]

Das DOS-Kommando läßt sich dann über die Windows-Taskverwaltung automatisieren.

===== Java-Client zum Entladen von Quell-Datenbanken =====
Zum Entladen aus dem operativen Vorsystem wird unter Informix dbaccess genutzt. Unter Postgres wird generell der SuperX-JAVA-Client zum Entladen genutzt, denn SuperX benötigt ein spezielles, an Informix angepasstes [[Kernmodul_Komponentenverwaltung#Format_der_Unload_Dateien_CSV|CSV-Format]], das sich mit Bordmitteln von Postgres (copy-Befehl) nicht erzeugen lässt. Es kann aber auch sinnvoll sein, aus der Informix-Datenbank mit SuperX-JAVA-Client zu entladen, z.B. wenn Sie kein UNIX-dbaccess auf dem Vorsystem installiert haben.

Wenn Sie das jew. operative Vorsystem im PUSH-Verfahren entladen wollen, d.h. die Rohdaten werden auf dem Vorsystem entladen und auf den SuperX-Rechner kopiert, dann müssen Sie spezielle Vorkehrungen treffen. SuperX nutzt generell zum Entladen eigene Java-Klassen. Beim Entladen im PULL-Verfahren sind diese Klassen vorhanden, denn die Entladeroutine läuft auf dem SuperX Rechner. Wenn Sie aber PUSH nutzen wollen, werden die SuperX-Java-Klassen auf dem Liefersystem benötigt, und die Entladeroutine muss konfiguriert sein. Im Folgenden nutzen wir das Beispiel "Entladen im Push-Verfahren aus SVA-GX unter Postgres". Gehen Sie dazu wie folgt vor:
* Kopieren Sie die Dateien
** superx*jar
** postgresql-*.jar
** jfor-0.7.2rc1.jar
* vom SuperX-Rechner im Verzeichnis $SUPERX_DIR/tomcat/webapps/superx/WEB-INF/lib auf den Quellrechner in ein Unterverzeichnis lib unter rohdaten (z.B. /home/sva/superx/rohdaten/lib). In rohdaten liegt die bisherige Entladeroutine (z.B. sva_unload.x).
* Kopieren Sie die *_ENV.sam -Datei nach *_ENV, also hier SVA_ENV.sam nach SVA_ENV
* Fügen Sie dann folgenden Passus in die Umgebungs-Datei der Entladeroutine, hier also SVA_ENV:
#Pfad zu den SuperX-Java-Libraries
#Der JDBC_CLASSPATH enthält alles, was der jdbc-Client in superx für den Datenbankzugriff braucht.
#jfor*.jar, postgresql*.jar
JDBC_CLASSPATH="$SVA_LOAD_PFAD/lib/superx5.0.jar:$SVA_LOAD_PFAD/lib/postgresql-42.2.19.jar:$SVA_LOAD_PFAD/lib/jfor-0.7.2rc1.jar"
export JDBC_CLASSPATH

Wenn dann noch die Variablen [[Kern_Installation_Upgrade#Anpassen_der_Datenbankparameter_db.properties|DB_PROPERTIES]] und LOGGER_PROPERTIES korrekt gesetzt sind, kann die Entladeroutine bei SX_CLIENT=jdbc (Wenn Sie unter Windows entladen, oder Informix ohne dbaccess entladen wollen) oder SX_CLIENT=psql (wenn Sie Postgres unter UNIX nutzen) mit Java entladen.

Danach können Sie das Entladescript ausführen:
sva_unload.x
Die Logdatei lautet sva_unload.err

Zum Kopieren der Rohdaten zum SuperX-Server passen Sie folgende Variablen an:

{| class="wikitable"
|-
! Variable
! Erläuterung
|-
|
| Wenn die Rohdaten beim Push-Verfahren nach dem Entladen vom SVA-Rechner auf den BI-Rechner kopiert werden sollen, dann werden für das Script sva_copy.x folgende Umgebungsvariablen benötigt:
|-
| COPY_METHOD
| Programm, das die Dateien kopiert; rsync, [[Kernmodul_Komponentenverwaltung#Einrichtung_von_SFTP|sftp]] und scp sind wählbar [Achtung: diese müssen dann betriebssystemseitig installiert sein].
|-
| REMOTE_DIR
| Verzeichnis, in das die Rohdaten auf dem BI-Rechner kopiert werden sollen, in der Regel ist dies "/home/superx/db/module/sva/rohdaten"
|-
| REMOTE_USER
| Der Unix-Username auf dem BI-Rechner, in der Regel "tomcat" oder "superx".
|-
| REMOTE_HOST
| Der Rechnername bzw. die IP-Nr. des BI-Rechners.
|}
Danach starten Sie
sva_copy.x
Die Logdatei lautet sva_copy.err

Weitere Entladeparameter werden in den modulspezifischen Administrationshandbüchern beschrieben.
{{Hinweis|Bei neuen SuperX-Versionen reicht es in der Regel, die modulspez. Dateien auszutauschen, also hier sva_unload.* etc.}}

== Update eines Moduls: Allgemeines Vorgehen ==
Wenn das Entladen aus dem Vorsystem geklappt hat (sofern es ein Vorsystem gibt), können Sie die Daten laden. Zum Update bzw. zum Laden der Rohdaten gehen in das Verzeichnis $SUPERX_DIR/db/module/-Modulname- und führen das Script aus:
-Modulname-_update.x
Die Logdatei lautet L_-Modulname-_UPDATE.log, im Mandantenfähigen Betrieb "L_-Modulname-_UPDATE-MANDANTID-.log".
Für die Aufnahme der Laderoutine in die crontab gibt es im gleichen Verzeichnis Musterscripte nach dem Namensmuster:
-Modulname-_update_cron.x
Je nach Push/Pull-Szenario können Sie auch den Unload darin starten oder nicht.

=== Modulupdate in mandantenfähigen Installationen ===
Der Modulupdate in mandantenfähigen Installation findet in einer SuperX-Installation statt, allerdings werden die einzelnen Scripte mit unterschiedlichen Umgebungsvariablen, wie sie in SQL_ENV.-MANDANTID- definiert ist, z.B. SQL_ENV.FHRO.
In der SQL_ENV.-MANDANTID- werden unterschiedliche Pfade für den jeweiligen *_LOAD_PFAD gesetzt, wobei in der Regel die Mandandid ein Unterverzeichnis vom "normalen" LOAD_PFAD ist. So ist z.B. beim COB-Modul folgender Pfad anzusetzen:
Normale SuperX-Installation:
COB_LOAD_PFAD=$SUPERX_DIR/db/module/cob/rohdaten
Mandantenfähige SuperX-Installation:
COB_LOAD_PFAD=$SUPERX_DIR/db/module/cob/rohdaten/FHRO
Unterhalb von FHRO befindet sich noch einmal die Entladeroutine sowie das Unterverzeichnis unl mit den Rohdaten. Dieses Verzeichnis FHRO kann der Einfahheit halber auch ein symbolischer Link auf den gemounteten COB-Rechner sein.
Durch Setzen der Mandantennummer in der Umgebungsvariable MANDANTID in der jeweiligen SQL_ENV des Mandanten werden die ETL-Scripte anders ausgeführt: Die Logdateien werden jeweils mit der Mandantennummer versehen (z.B. L_cob_updateFHRO.log), damit die Übersicht nicht verloren geht und der gleichzeitige Update mehrerer Mandanten in eine rsuperX-Installation möglich ist.
Außerdem können weitreichende Steuerungsmechanismen im Modulupdate eingesetzt werden: Nach jedem ETL-Schritt können optional mandantenspezifische Scripte aufgerufen werden. Diese müssen folgende Namenskonvention einhalten:
-Scriptname-_-MANDANTID-.sql
Also für eine hochschulspezifische Transformation im COB-Modul des Mandanten FHRO wird eine Datei namens
cob_trans_FHRO.sql
mit entsprechenden SQL-Anweisungen angelegt.

=== Format der Unload Dateien CSV ===
Generell gilt das Prinzip, daß Daten vom Vorsystem in CSV entladen werden, und dann in sog. Ladetabellen hochgeladen werden. Da CSV je nach DBMS unterschiedlich implementiert wird, hier eine kurze Beschreibung des Formats, das im wesentlichen den Vorgaben von Informix LOAD entspricht:
* Zeichenformat: UNIX LATIN1 oder UTF-8
* Feldtrenner: ^
* Satztrenner: Feldtrenner + UNIX NEWLINE
* Zeilenschaltung: Umbrüche innerhalb von Textfeldern sind als \ + NEWLINE codiert
* Feldtrenner, die im Textfeld vorkommen, werden mit "\" maskiert. Ebenso das Zeichen "\" selbst
* Die Datumsformate sind bei Datumsfeldern immer im deutschen Format (DD.MM.YYYY) vorgesehen
* Boolean-Werte werden durch "true" oder "false" codiert
* Der Dezimaltrenner ist ".", kein 1000-er Punkt bei Zahlen.
* Leerstrings und Leerzeichen werden als " " (Leerzeichen) exportiert.

== Upgrade eines Moduls: Allgemeines Vorgehen ==
Zum Upgrade bzw. zum Zurücksetzen des Moduls auf den Auslieferungszustand entpacken Sie das Paket in $SUPERX_DIR und gehen in das Verzeichnis $SUPERX_DIR/db/module/-Modulname-/upgrade und führen das Script aus:
-Modulname-_upgrade.x
Ausnahme: beim Kernmodul gibt es i.d.R. ein spezielles [[Kern_Installation_Upgrade#Standardvorgehen_beim_Upgrade|Upgrade Script]].

Die Logdatei lautet upgrade.log, im Mandantenfähigen Betrieb "upgrade-MANDANTID-.log".

Wenn Sie einen separaten Tomcat-Rechner betreiben, müssen Sie das Paket dort ebenfalls entpacken, und vom Datenbankserver die Datei $SUPERX_DIR/webserver/tomcat/webapps/superx/WEB-INF/dbforms-config.xml an die gleiche Stelle auf den Tomcat Rechner kopieren. Ein nochmaliges Ausführen des Upgrade Scriptes ist nicht nötig, weil dies nur die Datenbank betrifft.

== Hochschulspezifische Anpassung eines Moduls ==
=== Dateibasierte hochschulspezifische Anpassung ===
Nach der Installation bzw. beim Upgrade können Sie hochschuleigene SQL Scripte ausführen lassen. Erzeugen Sie dazu eine Datei
$SUPERX_DIR/db/module/-Modulname-/conf/customize.sql
bei Mandantenbetrieb
$SUPERX_DIR/db/module/-Modulname-/conf/customize-MANDANTID-.sql
und füllen Sie diese mit einem beliebigen Inhalt. Das Script wird beim Upgrade des Moduls automatisch am Ende ausgeführt.
=== Datenbankbasierte hochschulspezifische Laderegeln ===
Eine Laderoutine gliedert sich in die Schritte
#Unload: Entladen der CSV Dateien aus dem jew. Vorsystem
#Load: Upload der CSV Dateien
#Trans: Transformation der Daten
#Aggr: Aggregation der Daten
#Test: Test der Daten
#System: Standdatum bei Erfolg aktualisieren
Es ist möglich über sog. "Preparation"- oder "Finalize"-[[Kernmodul_Shellscripte#Hochschulspezifische_Transformationen_im_ETL-Prozess|Scripte]] die Laderoutine am Ende von LOAD bzw. TRANS anzupassen. Dieses Verfahren ist weiterhin möglich, ist aber bzgl. Clustering und Schreibzugriff recht unflexibel.

Es ist auch möglich im Browser hochschulspezifische Scripte am Ende des jeweiligen Schrittes einer Laderoutine anzulegen. Dies funktioniert so: Die Laderoutine führt zunächst den allgemeinen, von uns vorgegebenen Ladeschritt aus. Wenn dann eine Repository-Variable mit einem gewissen Namensschema existiert, wird sie ausgeführt. Das Namensschema lautet
<source lang="xml">
<<Kürzel der Komponente>>_<<Ladeschritt>>_CUSTOM
</source>.
* Bei Hauptladeroutinen ist dies
*# Laden: '''Kürzel der Komponente'''_load_CUSTOM, z. B. sos_load_CUSTOM
*# Transformation: '''Kürzel der Komponente'''_trans_CUSTOM, z. B. sos_trans_CUSTOM
*# Aggregation: '''Kürzel der Komponente'''_aggr_CUSTOM, z. B. sos_aggr_CUSTOM
* Bei Unterladeroutinen ist dies '''Kürzel der Komponente'''_'''ID des Ladeschritts'''_CUSTOM, also z. B. cob_trans_fin_busa_CUSTOM für die Unterladeroutine "Lade Buchungen aus FIN"

Um eine Variable neu einzurichten:
* Gehen Sie in den BI-Standardberichten auf Administration/Hochschul-Repository.
* Wählen Sie das jeweilige Sachgebiet und schicken Sie das Formular ab.
* Klicken Sie bei einer Beispielzeile auf '''Bearbeiten'''.
* Im neuen Fenster klicken Sie oben ganz rechts auf das Symbol '''Datensatz kopieren'''.
* Definieren Sie die Variable z. B.
** als Variablenname die ID z. B.: fin_load_CUSTOM
** Art der Variable: ein für Sie sprechender Schlüssel mit Modulkürzel, z. B. "fin_Laderegel"
** als Inhalt der Variable die gewünschten Befehle, z. B.
<source lang="sql">
update fin_buch_neu set ch110_institut=buchungsab_fb where length(buchungsab_fb)=5;
</source>
** aktiv=1
** gültig seit 1.1.1900
** gültig bis 1.1.3000
* Klicken Sie oben rechts auf das Häkchen-Symbol für '''Datensatz einfügen'''.
* Schließen Sie das Fenster.

Analog können Sie auch die [[Kernmodul_Komponentenverwaltung#Dateibasierte_hochschulspezifische_Anpassung|customize]]-Regeln" ins Repository verlagern. Hier heißt die Variable z.B. fin_install_CUSTOM.

== Entfernen eines Moduls ==
Wenn Sie ein Modul nicht mehr benötigen, starten Sie das Script 
$SUPERX_DIR/db/module/-Modulname-/-Modulname-_modul_entfernen.x. 
Dieses Script löscht alle Tabellen, Prozeduren und Abfragen aus der Datenbank, und löscht auch die Einträge im Themenbaum. Danach können Sie den Pfad $SUPERX_DIR/db/module/-Modulname-löschen.
Wenn Sie nur die Inhalte der Daten- und Hilfstabellen des Moduls löschen wollen (z.B. aus Datenschutzgründen), ohne das ganze Modul zu deinstallieren, können Sie dies mit folgendem Befehl tun:
DOSQL $SUPERX_DIR/db/module/-Modulname-/-Modulname-_purge_pg.sql (für Postgres) 
bzw. 
DOSQL $SUPERX_DIR/db/module/-Modulname-/-Modulname-_purge_ids.sql (für Informix)

Modul GXStage Nutzungshandbuch

2026-07-09T09:17:31Z

Andrek:

=Allgemeine Hinweise=
Der Finanzbericht ist eine web-basierte Anwendung auf Basis des Auswertesystems SuperX. Für jeden User werden spezifische Rechte auf Finanzstellen und/oder Haushaltsprogramme gepflegt.

Bei den Berichten handelt es sich um ein reines Auswertesystem ohne Zugriffsmöglichkeit in das „echte Buchungssystem“. Sie haben nicht die Möglichkeit, selbst Auszahlungen vorzunehmen oder andere Buchungen durchzuführen. Somit besteht auch nicht die Gefahr, dass durch Ihre Auswertungen Daten in SAP beschädigt werden können.

Im Finanzbericht werden immer die Daten zum Buchungsschluss des Vortages dargestellt.

Am 30. Juli 2015 finden Sie im Finanzbericht die Daten des Buchungsabschlusses vom 29. Juli 2015.

Bitte beachten Sie die Vorgaben des Datenschutzes.

Als Standarduser werden Ihnen nur die Werte auf zahlungswirksamen Finanzpositionen angezeigt, als Experte können Sie auswählen, ob auch Finanzpositionen mit statistischer Fortschreibung berücksichtigt werden sollen, vergl. dazu Kapitel [[Modul_GXStage_Nutzungshandbuch#Für Experten – auch Finanzposition mit statistischer Fortschreibung berücksichtigen|Für Experten – auch Finanzposition mit statistischer Fortschreibung berücksichtigen]].

Wichtiger Hinweis:

Der Administrator kann einstellen, dass bestimmte Daten, z.B. Buchungen zu Personalkosten nicht in die Kontostände eingerechnet werden und auch nicht als einzelne Buchungen angezeigt werden.

Derzeit ist das:

* An der HAW Karlsruhe der Fonds 80561002
* An der HAW Reutlingen der Fonds 80641001
* An der HAW Pforzheim der Fonds 80621002

=Anmeldung am System=
Melden Sie sich in SuperX mit Ihrer Kennung und Ihrem Passwort an.

[[Bild:GX-Stage-Modul-Benutzer-anmeldung.png|600px]]

Danach erscheint links ein Themenbaum, der je nach Ihren Rechten unterschiedlich aussehen kann.

Klicken Sie auf den Menüpunkt „Kaufmänn. Auswertungen“

[[Bild:GX-Stage-Modul-Benutzer-themenbaum.png|600px]]

Es erscheinen auf der rechten Seite vier Berichte, die Sie anklicken können.

Wenn Sie nach einer Auswertung wieder zurück zu dieser Übersicht wollen, können Sie immer im linken Navigationsteil wieder auf „Kaufmänn. Auswertungen“ klicken.

=SAP-Budget nach Finanzstelle=
Dieser Bericht ist für Sie geeignet, wenn Sie für mindestens eine Finanzstelle Berechtigung haben. Wenn Sie nur für einzelne Haushaltsprogramme die Berechtigung haben, nehmen Sie den Bericht „SAP Budget nach HHProgramm“.

Beachten Sie, dass die Gesamtsumme nur die Summe der ausgewählten Finanzstellen darstellt. Wenn Sie eine Berechtigung für zusätzliche Haushaltsprogramme auf anderen Finanzstellen haben, nutzen Sie den Bericht SAP-Budget nach HHProgramm, um Ihren Gesamtkontostand abzurufen.

==Die Maske==
Nach dem Anklicken des Berichts im Menü erscheint folgende Maske:

[[Bild:GX-Stage-Modul-Benutzer-budget_nach_finanzstelle.png|600px]]

Wählen Sie das gewünschte Jahr aus. Bei „Details zu Budgetarten“ können Sie auswählen, ob Sie diese sehen möchten oder nicht. Dies wird weiter unten noch am Beispiel gezeigt.

==Auswahl Finanzstelle==
Als Nächstes wählen Sie eine Finanzstelle aus, dies ist bei diesem Bericht obligatorisch.

Klicken Sie auf den Button Finanzstelle, es erscheint ein Auswahldialog:

[[Bild:GX-Stage-Modul-Benutzer-auswahl_finanzstelle.png|600px]]

Wählen Sie die gewünschte Finanzstelle. Wenn Sie für mehrere Finanzstellen die Berechtigung haben, können Sie eine oder mehrere Finanzstellen auswählen.

Der Hinweis „(Auswahl)“ hinter der Bezeichnung wie im Beispiel nach Hochschule und HsKA Allg. bedeutet, dass Sie nicht für die komplette Finanzstelle einschließlich untergeordneter die Berechtigung haben, sondern eben nur für eine Auswahl.

Bei Bedarf können Sie auch den „Suchen“ Button benutzen.

Weiterhin ist möglich, eine Finanzstellennummer auch direkt einzutippen, vergl. dazu [[Modul_GXStage_Nutzungshandbuch#Direkteingabe von Schlüsseln|Direkteingabe von Schlüsseln]].

Wenn Sie die Berechtigung für mehrere Finanzstellen haben, könnte es interessant sein, die „organisatorisch Sicht“ auf Finanzstellen zu nutzen. Klicken Sie dazu auf den Button „Sichtauswahl“.

Es öffnet sich ein Dialog, in dem Sie die „organisatorische Sicht“ auswählen und OK anklicken.

[[Bild:GX-Stage-Modul-Benutzer-sicht_organisatorisch.png|600px]]

Danach öffnen sich diese Sicht und Sie haben die Möglichkeit, z.B. eine Fakultät auszuwählen.

[[Bild:GX-Stage-Modul-Benutzer-sicht_organisatorisch2.png|600px]]

Das war die Auswahl der Finanzstelle.

==Auswahl Haushaltsprogramm==
Noch mal die Auswahlmaske:

[[Bild:GX-Stage-Modul-Benutzer-budget_nach_finanzstelle2.png|600px]]

Als Nächstes gilt es festzulegen, welche Haushaltsprogramme/Innenaufträge berücksichtigt werden sollen. Standardmäßig ist das Dummy-Haushaltsprogramm (9999) vorausgewählt, so dass Sie nur Kontostände sehen, die direkt die Finanzstelle betreffen, nicht die von weiteren Haushaltsprogrammen.

Sie können den Button „Haushaltsprog./Innenauftrag“ anklicken. Es öffnet sich ein Dialog.

[[Bild:GX-Stage-Modul-Benutzer-button_hhprog.png|600px]]

Wenn Sie im Feld vorher bestimmte Finanzstellen ausgewählt haben, werden bei diesem Button nur die HHProgramme angezeigt, die für die gewählten Finanzstellen relevant sind.

Falls Sie andere Haushaltsprogramme sehen möchten, müssen Sie ggfs. einmal den Button „Finanzstelle“ anklicken und dann auf „Leeren“.

Wenn Sie die Gesamt-Kontostände für die Finanzstellen sehen möchten, klicken Sie auf den Button „Leeren“ - dann wird nicht mehr auf das Dummy-Haushaltsprogramm eingeschränkt.

Alternativ können Sie ein oder mehrere Haushaltsprogramme auswählen, für die Sie den Gesamtkontostand sehen möchten. Bitte beachten Sie, dass dieser Bericht dann nur die Gesamtwerte auf der Finanzstelle für die gewählten Haushaltsprogramme anzeigt. Wenn Sie Details zu den einzelnen Haushaltsprogrammen benötigten, können Sie statt dessen den Bericht „SAP Budget nach HHProg“ benutzen.

Noch mal die Maske:

[[Bild:GX-Stage-Modul-Benutzer-budget_nach_finanzstelle2.png|600px]]

Wenn an Ihrer Hochschule mit Kurz-IDs für Haushaltsprogramme gearbeitet wird, können Sie beim Button Haushaltsprog./Innenauftrag auf „Leeren“ Klicken und dann direkt die KurzID des gewünschten Haushaltsprogramms eingeben.

==Optionale Einschränkung auf Fonds==
Bei Bedarf können Sie auf bestimmte Fonds einschränken, klicken Sie dazu auf den Button „Fonds“. Bitte beachten Sie, dass bestimmte Fonds ggfs. generell nicht berücksichtigt werden, siehe dazu unter 1. Allgemeine Hinweise.

==Netto oder Brutto?==
Schließlich wählen Sie noch, ob Sie Netto oder Brutto Beträge sehen möchten und klicken auf „Abschicken“.

==Abschicken==
Wenn Sie mehr mit den Berichten arbeiten, wird Ihnen vielleicht auffallen, dass die Auswahlwerte, die Sie in einem Bericht getroffen haben, standardmäßig auch als Vorauswahl für einen anderen Bericht genommen werden. Falls Sie diese Vorbelegungen mal entfernen möchten, können Sie den Button „Zurücksetzen“ anklicken.

==Ergebnisdarstellung==
Die Ergebnisdarstellung sieht so aus:

[[Bild:GX-Stage-Modul-Benutzer-budget_nach_finanzstelle3.png|600px]]

Man sieht auf einen Blick, dass auf der Finanzstelle ein Budget von 9.969,70 Euro eingestellt wurde. Einnahmen und Mittelbindungen wurden nicht gebucht. Es gab Ausgaben von 13.250,13 Euro. Verfügbar sind noch -3290,43. Falls Mittelbindungen gebucht wurden, unterscheidet sich natürlich das Verfügbar ohne Mittelbindungen von der Verfügbar-Spalte.

Alles hier im Beispiel sind natürlich fiktive Zahlen.

==Durchklicken zu Einzelbuchungen==
Die blau dargestellten Zahlen in der Ergebnistabelle kann man anklicken, um sich die Einzelbuchungen zu diesen Werten anzeigen zu lassen. Klickt man z.B. auf die -13250,13 bei Ausgaben, erscheint folgende Darstellung in einem neuen Fenster:

[[Bild:GX-Stage-Modul-Benutzer-budget_nach_finanzstelle-buchungen.png|600px]]

Es wird noch mal die gewählte Finanzstelle, Haushaltsprogramm, Finanzposition, ggfs. Zahlungspartner (Kreditor/Debitor), der Werttyp, Buchungsdatum, Betrag, Belegnummer und Buchungstext dargestellt.

Standardmäßig werden bei der Darstellung von Ausgaben die Werttypen inkl. Rechnungen und Zahlungen dargestellt, wenn Sie nur die Zahlungen sehen möchten, klicken Sie auf den kleinen rot umrandeten Zurück-zur-Maske-Button:

[[Bild:GX-Stage-Modul-Benutzer-buchungsbericht_zurueck.png|600px]]

Sie kommen dann von der Ergebnistabelle zur Buchungsberichtsmaske mit den aktuellen Einstellungen.

[[Bild:GX-Stage-Modul-Benutzer-buchungsbericht_maske_werttyp.png|600px]]

Klicken Sie auf den Button „Werttyp/Budgetart“ und wählen 57-Zahlungen aus. Wenn Sie dann unten auf „Abschicken“ klicken, erscheinen nur die Zahlungen zu den aktuell ausgewählten Parametern.

==Darstellung von Hierarchieebenen==
Wenn Sie die Berechtigung für mehrere Finanzstellen haben, die unter eine Hierarchie hängen (insb. bei organisatorischer Sicht), kann die Ergebnisdarstellung so aussehen:

[[Bild:GX-Stage-Modul-Benutzer-budget_nach_finanzstelle4.png|600px]]

Dies ist folgendermaßen zu lesen.

In der ersten Zeile (Gliederung 1) sieht man die Gesamtwerte für alle untergeordneten Finanzstellen. Bei den Ausgaben z.B. -3.313,734,43 Euro. Vor der Finanzstelle ist jeweils ein kleiner gelbes Ordnersymbol dargestellt, wie im Windows-Dateiexplorer. Sie können diese Ordner auf- und zuklappen. Man sieht in den Zeilen mit der Gliederungsebene 2, wie sich die Ausgaben über die einzelnen Fächergruppen verteilen. Die Fächergruppe BI wurde wiederum aufgeklappt und man sieht, wie sich die Ausgaben von 452.748,11 Euro auf die Fachgruppe Bauing. und das Bauingenieurwesen verteilen.

Wenn Sie die Daten nach Excel exportieren möchten, klicken Sie auf den Text „XLS“ im Exportmenü.

[[Bild:GX-Stage-Modul-Benutzer-excelexport1.png|600px]]

Danach werden Sie gefragt, ob Sie alle Daten exportieren möchten oder nur die aktuell sichtbaren:

[[Bild:GX-Stage-Modul-Benutzer-excelexport2.png|600px]]

Wenn Sie die Darstellung in Excel so haben möchten, wie Sie die Tabelle gerade aufgeklappt haben, klicken Sie auf „Nur die sichtbaren Tabellenzeilen“, wenn Sie alle Daten möchten, klicken Sie auf „Alle Daten“.

Bitte beachten Sie, dass die Nutzung der Summenfunktion in Excel selbst nicht sinnvoll ist, weil die oberen Hierarchieebenen schon die Teilsummen der untergeordneten Finanzstellen enthalten.

==Gesamtsumme bei Auswahl mehrerer Finanzstellen==
Wenn Sie mehrere Finanzstellen im Bericht einzeln ausgewählt haben, z.B.

[[Bild:GX-Stage-Modul-Benutzer-auswahl-finanzstelle_mehrfach.png|600px]]

wird unter der Darstellung der Kontostände für die einzelnen Finanzstellen, noch mal die Gesamtsumme für die ausgewählten Finanzstellen angezeigt.

[[Bild:GX-Stage-Modul-Benutzer-budget_nach_finanzstelle5.png|600px]]

Beachten Sie, dass die Gesamtsumme nur die Summe der ausgewählten Finanzstellen darstellt. Wenn Sie eine Berechtigung für zusätzliche Haushaltsprogramme auf anderen Finanzstellen haben, nutzen Sie den Bericht SAP-Budget nach HHProgramm, um Ihren Gesamtkontostand abzurufen.

==Details nach Finanzposition==
In den einzelnen Zeilen der Kontodarstellung gibt es eine Spalte „Details Fipos“

[[Bild:GX-Stage-Modul-Benutzer-budget_nach_finanzstelle5b.png|600px]]

Hier als letzte Spalte zu sehen.

Wenn Sie für die erste Zeile, die Automatisierungstechnik L, Details pro Finanzposition sehen möchten, klicken Sie auf das gelbe Symbol in der ersten Zeile.

Es öffnet sich ein neues Fenster:

[[Bild:GX-Stage-Modul-Benutzer-fipos2.png|600px]]

In der ersten Zeile steht noch einmal der Gesamtwert über alle Finanzpositionen. Die gelben Ordnersymbole vor den Finanzpositionen können Sie aufklappen, um einzelne Finanzpositionen zu betrachten. Wie schon vorher erläutert, können die blau dargestellten Eurobeträge angeklickt werden, um sich die Einzelbuchungen anzusehen. Bei den Ausgaben werden die relevanten Monate dargestellt und dann die Gesamtsumme der Ausgaben.

In der Standardhierarchie im Finanzpositionsbericht wird auf der Topfinanzposition 6 Drittmittel nur der gebuchte Budgetwert angezeigt. Die Ausgaben werden auf die Einzelfinanzpositionen gebucht und auf den TopFipos 1-4 in Summe angezeigt.

==Details zu Budgetarten==
Im Normalfall werden keine Details zu den einzelnen Budgetarten benötigt. Daher steht das zweite Auswahlfeld der Maske „Details zu Budgetarten“ standardmäßig auf Nein.

[[Bild:GX-Stage-Modul-Benutzer-budget_nach_finanzstelle2.png|600px]]

Wenn Sie Details benötigen, wählen Sie hier „Ja“ aus.

Nach dem Abschicken der Maske erscheinen zusätzliche Spalten:

[[Bild:GX-Stage-Modul-Benutzer-budgetarten.png|600px]]

Es erscheinen nach dem Finanzstellennamen die zwei Spalten Drittmittel und Reste und dann Gesamtbudget. Das Gesamtbudget von 1,9 Mio setzt sich also aus den zwei Budgetarten Drittmittel und Reste zusammen.

=SAP-Budget nach HHProgramm=
Wählen Sie diesen Bericht, wenn Sie Details zu einzelnen Haushaltsprogrammen sehen möchten. Wenn Sie keine Berechtigung für komplette Finanzstellen haben, ist dieser Bericht Ihre erste Anlaufstelle.

Außerdem ist er praktisch, wenn Sie neben der Berechtigung für einzelne Finanzstellen noch Rechte auf zusätzliche Haushaltsprogramme haben. In dem Fall können Sie in diesem Bericht Ihren „Gesamtkontostand“ einsehen.

==HHProgramm – die Maske==
Nach dem Anklicken im Menü erscheint folgende Maske:

[[Bild:GX-Stage-Modul-Benutzer-budget_nach_hhprog1.png|600px]]

Wählen Sie das gewünschte Jahr aus.

Optional können Sie auf eine oder mehrere Finanzstellen einschränken. Wenn Sie keine Berechtigung für komplette Finanzstellen haben, lassen Sie den Button links liegen.

Zur Bedienung des Buttons vergl.[[Modul_GXStage_Nutzungshandbuch#Auswahl Finanzstelle|Auswahl Finanzstelle]].

Wählen Sie optional ein Haushaltsprogramm aus oder geben eine KurzID ein (vergl. [[Modul_GXStage_Nutzungshandbuch#Auswahl Haushaltsprogramm|Auswahl Haushaltsprogramm]] ).

Schließlich können Sie bei Bedarf auf einen oder mehrere Fonds einschränken und klicken auf den Button „Fonds“.

Wählen Sie aus, ob Sie Brutto oder Nettobeträge sehen wollen und klicken Sie auf „Abschicken“.

Wenn Sie mehr mit den Berichten arbeiten, wird Ihnen vielleicht auffallen, dass die Auswahlwerte, die Sie in einem Bericht getroffen haben, standardmäßig auch als Vorauswahl für einen anderen Bericht genommen werden. Falls Sie diese Vorbelegungen mal entfernen möchten, können Sie den Button „Zurücksetzen“ anklicken.

==HHProgramm – die Ergebnistabelle==
Die Ergebnisdarstellung kann so aussehen:

[[Bild:GX-Stage-Modul-Benutzer-hhprog_erg.png|600px]]

Pro Haushaltsprogramm werden das Budget, die Einnahmen, Mittelbindung, Ausgaben und das Verfügbar mit/ohne Mittelbindung dargestellt.

Wie in Kapitel [[Modul_GXStage_Nutzungshandbuch#Durchklicken zu Einzelbuchungen|Durchklicken zu Einzelbuchungen]] beschrieben, können Sie die blauen Zahlen anklicken, um sich Einzelbuchungen anzusehen.

In der letzten Spalte gibt es die Möglichkeit auch „Details zu Finanzpositionen“ abzurufen, vergl. Kapitel [[Modul_GXStage_Nutzungshandbuch#Details nach Finanzposition|Details nach Finanzposition]].

=SAP-Finanzpositionsbericht=
Dieser Bericht kann per Link direkt von den Berichten SAP-Budget nach Finanzstelle bzw. HHProg aufgerufen werden. Sie können ihn aber auch manuell aufrufen.

==Finanzpositionen – die Maske==
Die Maske sieht folgendermaßen aus:

[[Bild:GX-Stage-Modul-Benutzer-finanzpos_maske.png|600px]]

Wählen Sie das gewünschte Jahr aus.

Optional können Sie auf eine oder mehrere Finanzstellen einschränken. Wenn Sie keine Berechtigung für komplette Finanzstellen haben, lassen Sie den Button links liegen.

Zur Bedienung des Buttons vergl. [[Modul_GXStage_Nutzungshandbuch#Auswahl Finanzstelle|Auswahl Finanzstelle]] in Kapitel 3.

Wählen Sie optional ein Haushaltsprogramm aus oder geben eine KurzID ein (vergl. [[Modul_GXStage_Nutzungshandbuch#Auswahl Haushaltsprogramm|Auswahl Haushaltsprogramm]] in Kapitel 3).

Schließlich können Sie bei Bedarf auf einen oder mehrere Fonds einschränken und klicken auf den Button „Fonds“.

Wenn Sie nur bestimmte Finanzpositionen sehen möchten, klicken Sie auf den Button „Finanzposition“.

Schließlich wählen Sie aus, ob Sie Brutto oder Nettobeträge sehen wollen und klicken Sie auf „Abschicken“.

Wenn Sie mehr mit den Berichten arbeiten, wird Ihnen vielleicht auffallen, dass die Auswahlwerte, die Sie in einem Bericht getroffen haben, standardmäßig auch als Vorauswahl für einen anderen Bericht genommen werden. Falls Sie diese Vorbelegungen mal entfernen möchten, können Sie den Button „Zurücksetzen“ anklicken.

==Finanzpositionen – die Ergebnisdarstellung==
Die Ergebnisdarstellung sieht z.B. so aus:

[[Bild:GX-Stage-Modul-Benutzer-fipos2.png|600px]]

In der ersten Zeile steht der Gesamtwert über alle Finanzpositionen. Die gelben Ordnersymbole vor den Finanzpositionen können Sie aufklappen, um einzelne Finanzpositionen zu betrachten. Wie schon vorher erläutert, können die blau dargestellten Eurobeträge angeklickt werden, um sich die Einzelbuchungen anzusehen. Bei den Ausgaben werden die relevanten Monate dargestellt und dann die Gesamtsumme der Ausgaben. Zu den Möglichkeiten beim Export vergl. auch [[Modul_GXStage_Nutzungshandbuch#Darstellung von Hierarchieebenen|Darstellung von Hierarchieebenen]].

In der Standardhierarchie im Finanzpositionsbericht wird auf der Topfinanzposition 6 Drittmittel nur der gebuchte Budgetwert angezeigt. Die Ausgaben werden auf die Einzelfinanzpositionen gebucht und auf den TopFipos 1-4 in Summe angezeigt.

=SAP-Buchungsbericht=
Der SAP-Buchungsbericht kann durch Anklicken von blau dargestellten Eurobeträgen aufgerufen werden oder auch manuell, in dem man ihn im Themenbaum auswählt.

[[Bild:GX-Stage-Modul-Benutzer-themenbaum.png|600px]]

==Buchungsbericht – die Maske==
Die Maske sieht so aus:

[[Bild:GX-Stage-Modul-Benutzer-buchungsbericht_maske.png|600px]]

Das gewünschte Jahr muss ausgewählt werden. Optional kann als Zweites eine Periode ausgewählt werden.

Als Drittes folgt die Buchungsart. Sie haben folgende Auswahlmöglichkeiten:

[[Bild:GX-Stage-Modul-Benutzer-buchungbericht_bucharten.png|600px]]

Je nach dem, was Sie hier auswählen, können Sie im nächsten Feld „Werttyp/Budgetart“ noch optional weiter auf bestimmte Werttypen oder Budgetarten einschränken.

Zur Auswahl der Finanzstelle vergleiche [[Modul_GXStage_Nutzungshandbuch#Auswahl Finanzstelle|Auswahl Finanzstelle]].

Zur Auswahl eines Haushaltsprogrammes vergleiche [[Modul_GXStage_Nutzungshandbuch#Auswahl Haushaltsprogramm|Auswahl Haushaltsprogramm]].

Weiterhin können Sie optional auf bestimmte Fonds oder Zahlungspartner (=Debitoren/Kreditoren) einschränken.

Wenn Sie auf Zahlungspartner klicken, erscheint folgender Dialog:

[[Bild:GX-Stage-Modul-Benutzer-buchungbericht_zp.png|600px]]

Anders als in anderen Felder sind nicht Zahlungspartner (Debitoren/Kreditoren) nicht nach Schlüssel sortiert, sondern nach Anfangsbuchstabe. Wenn Sie also die AA Pharma AG suchen, klappen Sie den Menüpunkt Ax auf. Oder Sie klicken auf den „Suchen“-Button, geben im Textfeld „AA Ph“ ein und dann auf OK.

In den weiteren Feldern der Buchungsberichtsmaske können Sie Buchungsdatum von/bis und Betrag von/bis angeben.

Als Letztes werden verschiedene Sortiermöglichkeiten für die Ergebnisdarstellung angeboten.

==Buchungsbericht – die Ergebnisdarstellung==
Es erscheint folgende Darstellung in einem neuen Fenster:

[[Bild:GX-Stage-Modul-Benutzer-budget_nach_finanzstelle-buchungen.png|600px]]

Es wird die Finanzstelle, Haushaltsprogramm, Finanzposition, ggfs. Zahlungspartner (Kreditor/Debitor), der Werttyp, Buchungsdatum, Betrag, Belegnummer und Buchungstext dargestellt.

=Für Experten – auch Finanzposition mit statistischer Fortschreibung berücksichtigen=
Wenn Ihr Admin Ihnen dies freigeschaltet hat, können Sie entscheiden, ob nur zahlungswirksame Finanzpositionen berücksichtigt werden sollen (=Standard) oder alle Finanzpositionen inkl. solche mit statistischer Fortschreibung.

Bei den Berichten SAP-Buchungsbericht, SAP Budget nach Finanzstelle und SAP Budget nach HHProg haben Sie ein zusätzliches Auswahlfeld „Finanzpositionswahl“.

[[Bild:GX-Stage-Modul-Benutzer-fipos_alle1.png|600px]]

Wählen Sie bei Finanzpositionswahl den Eintrag „alle (inkl. Stat. Fortschreibung)“.

Beim Durchklicken zum Finanzpositionsbericht und zu den Einzelbuchungen wird Ihre Auswahl automatisch berücksichtigt.

Wenn Sie den SAP-Finanzpositionsbericht direkt aufrufen und alle Finanzpositionen sehen möchten, gehen Sie wie folgt vor.

Wenn Sie auf den Button „Finanzposition“ klicken, ist die Voreinstellung die „reguläre Sicht“ mit nur zahlungswirksamen Einnahmen/Ausgaben.

[[Bild:GX-Stage-Modul-Benutzer-fipos_alle2.png|600px]]

Klicken Sie auf „Sichtauswahl“.

[[Bild:GX-Stage-Modul-Benutzer-fipos_alle3.png|600px]]

Wählen Sie die Sicht „inkl. Stat. Fortschreibung“ aus und klicken auf OK.

Die Darstellung ändert sich:

[[Bild:GX-Stage-Modul-Benutzer-fipos_alle4.png|600px]]

Diese Ansicht wird auch für die Ergebnisdarstellung benutzt.

=Weitere Optionen=
==Direkteingabe von Schlüsseln==
Geübte Anwender arbeiten lieber bei Maskenfeldern, die aus Dialogboxen oder Klappmenüs bestehen, mit der direkten Schlüsseleingabe. Wenn Sie den Schlüssel z.B. einer Finanzstelle auswendig wissen, geht dies u.U. schneller als die Auswahl im Dialog-Baum.

Wählen dazu das Punktsymbol auf einer Maske an:

[[Bild:GX-Stage-Modul-Benutzer-punktfunktion1.png|600px]]

Danach erscheinen gelbe Eingabefelder in die Sie direkt eine Eingabe machen können:

[[Bild:GX-Stage-Modul-Benutzer-punktfunktion2.png|600px]]

Wenn Mehrfachauswahl möglich ist, können Sie mit Komma getrennt auch mehrere Werte eintragen oder Sie arbeiten mit der Sternchen Funktion, geben z.B. 80562* ein. Dann werden alle HHProgramme selektiert, die mit 80562 anfangen.

==Arbeiten mit der Sternchen * Funktion==
Siehe unter [[Modul_GXStage_Nutzungshandbuch#Direkteingabe von Schlüsseln|Direkteingabe von Schlüsseln]]

==Exportfunktion==
Im Exportmenü oben auf der Maske können Sie wählen zwischen Druckversion, XML, PDF, XLS (Excel) oder auch CSV-Export. Druckversion, Excel und PDF sind natürlich die meist genutzten.

[[Bild:GX-Stage-Modul-Benutzer-exportmenue.png|600px]]

Wenn in einer Ergebnistabelle mehrere Hierarchieebenen vorhanden sind – man also per Ordnersymbol Zeilen auf- bzw. zuklappen gibt es beim Export die Möglichkeit alle Daten zu exportieren oder nur die aktuell sichtbaren, vergl. dazu auch [[Modul_GXStage_Nutzungshandbuch#Darstellung von Hierarchieebenen|Darstellung von Hierarchieebenen]].

==Lesezeichen==
Einen besonderen Komfort stellen die speziellen SuperX-Lesezeichen dar.

Vermutlich werden Sie für bestimmte Haushaltsprogramme oder Ihre Finanzstelle/n immer wieder den entsprechenden Bericht mit den gleichen Einstellungen aufrufen wollen.

Statt jedes Mal im Themenbaum die Maske anzuklicken, die Parameter einzustellen und dann auf Abschicken zu klicken, können Sie folgendes machen.

Wählen Sie den oft benötigten Bericht aus und stellen die Parameter wie gewünscht ein, z.B.

[[Bild:GX-Stage-Modul-Benutzer-lesezeichen1.png|600px]]

Klicken Sie dann auf Abschicken, es erscheint die Ergebnistabelle:

[[Bild:GX-Stage-Modul-Benutzer-lesezeichen2.png|600px]]

Klicken Sie dann oben auf das Lesezeichensymbol (Büroklammer).

Es erscheint folgender Dialog.

[[Bild:GX-Stage-Modul-Benutzer-lesezeichen3.png|600px]]

Klicken Sie wie angegeben mit der rechten Maustaste auf diesen Link.

Im Firefox sieht der Dialog dann so aus:

[[Bild:GX-Stage-Modul-Benutzer-lesezeichen4.png|600px]]

Geben Sie dem Lesezeichen einen aussagekräftigen Namen und Klicken dann auf „Speichern“.

Anschließend steht das Lesezeichen Ihnen wie ein normales Browserlesezeichen im Lesezeichenmenü von Firefox zur Verfügung.

Im InternetExplorer (Edge) sieht der Dialog etwas anders aus, wenn Sie mit der rechten Maustaste auf den Link geklickt haben:

[[Bild:GX-Stage-Modul-Benutzer-lesezeichen5.png|600px]]

Wählen Sie hier den vorletzten Punkt „Zu Favoriten“ hinzufügen.

Danach erscheint folgender Dialog:

[[Bild:GX-Stage-Modul-Benutzer-lesezeichen6.png|600px]]

Geben Sie wieder einen aussagekräftigen Namen ein und klicken auf „Hinzufügen“. Danach steht das Lesezeichen Ihnen unter den Favoriten des InternetExplorers zur Verfügung.

Beachten Sie bei einem Lesezeichen werden die eingestellten Parameter gespeichert, nicht der Stand der Daten. Wenn Sie ein Lesezeichen am 1.7. erstellt haben und am 20.7. wieder aufrufen, bekommen Sie -wie üblich- den Datenstand vom Vortag als dem 19.7. .

Der Stand der Daten wird immer am Ende der Legende angezeigt:

[[Bild:GX-Stage-Modul-Benutzer-stand_der_daten.png|600px]]

Falls Sie den Kontostand zu einem bestimmten Stichtag speichern möchten, nutzen Sie die Druckversion, Excel- oder PDF-Exportfunktion – dabei gilt es natürlich die Datenschutzbestimmungen einzuhalten.

==Weitere Funktionen==
Es gibt noch einige weitere Funktionen, die für fortgeschrittene User interessant sein könnten, z.B. das Ausblenden oder Umsortieren von Ergebnisspalten oder die Änderung der Sortierreihenfolge von Ergebnissen.

Hier sei auf das allgemeine Benutzerhandbuch verwiesen: [http://benutzerhandbuch.superx-projekt.de/ SuperX-Benutzerhandbuch], Kapitel 3.

Modul GXStage Konfigurationshandbuch

2026-07-09T09:06:44Z

Andrek:

=Einführung=

Das GX-Stage-Modul wird derzeit für SAP-Finanzberichte in SuperX genutzt. Dieses Konfigurationshandbuch beschreibt die administrativen Einstellungen für das Modul, insbesondere das Customizing, die Rechtevergabe auf Finanzstellen und Haushaltsprogramme sowie die Einrichtung geeigneter Benutzergruppen.

==Installation des Moduls==

Die Installation des Moduls ist in der GXSTAGE-Installationsanleitung beschrieben:

[https://superxhosting.de/wiki/index.php/GXSTAGE_Installationsanleitung GXSTAGE Installationsanleitung]

=Customizing=

==Bestimmte Daten, z. B. Fonds mit Personalbuchungen, nicht anzeigen==

Über die Repository-Variable '''GXSTAGE_CUSTOM''' können bestimmte Daten aus den GX-Stage-Auswertungen ausgeschlossen werden. Das ist beispielsweise sinnvoll, wenn Fonds mit Personalbuchungen nicht in den Berichten erscheinen sollen.

Gehen Sie dazu als Administrator/-in in den Bereich '''Administration Kaufmännische Auswertungen / Prüfprotokoll Kaufmännische Auswertungen'''. Öffnen Sie dort oben links unter '''Weitere Einstellungen''' den Punkt '''Filter und Variablen'''.

Im neuen Fenster geben Sie oben rechts bei '''Variable suchen''' den Suchbegriff '''GXSTAGE_CUSTOM''' ein. Wenn die Variable bereits vorhanden ist, können Sie sie bearbeiten. Andernfalls legen Sie sie neu an.

[[Bild:GX-Stage-Modul-Konfiguration-Gxstage_custom.png|600px]]

Tragen Sie im Inhalt der Variable einen passenden SQL-Abschnitt ein und speichern Sie die Änderung. Ein Beispiel zum Ignorieren des Fonds 80561002 lautet:

<source lang="sql">
and ggnr!='80561002'
</source>

{{Achtung|Der SQL-Abschnitt muss syntaktisch zur bestehenden WHERE-Bedingung passen. Im Screenshot fehlt beispielsweise noch ein <code>and</code>. Wenn nach der Änderung ein SQL-Fehler auftritt, muss die Bedingung in der Repository-Variable korrigiert werden.}}

Nach dem Speichern muss der SuperX-Manager-Cache aktualisiert werden. Klicken Sie dazu oben rechts auf '''SuperX Manager''' und anschließend im neuen Fenster auf '''Server-Cache aktualisieren'''. Testen Sie danach die betroffenen Berichte.

==Weitere einstellbare Parameter==

Die folgenden Parameter können im Repository angepasst werden:

{| class="wikitable" width="99%"
! width="25%" bgcolor="#CCE1EF"|Variable
! width="35%" bgcolor="#CCE1EF"|Defaultwert / Beispiel
! width="40%" bgcolor="#CCE1EF"|Beschreibung
|-
| GXSTAGE_DUMMY_HHPROG
| <code>9999</code>
| Nummer des Dummy-Haushaltsprogramms.
|-
| GXSTAGE_CUSTOM
| <code>and 1=1</code>
| Allgemeine Einschränkung für das GX-Stage-Modul.
|-
| GXSTAGE_IGNORE_EINNAHMEN_BRUTTO_FIPOS
| <code>and sachkonto not in ('400000101', '48000100', '48000199','48100000', '40000901')</code>
| Steuerkonten, die für Einnahmen netto nicht berücksichtigt werden sollen.
|-
| GXSTAGE_IGNORE_AUSGABEN_BRUTTO_FIPOS
| <code>and sachkonto not in ('26000000', '26000099', '26200020','26200029')</code>
| Steuerkonten, die für Ausgaben netto nicht berücksichtigt werden sollen.
|-
| GXSTAGE_ADAPT_FIPOS_TYPE
| <code>update gxstage_fipos set potyp='3' where variante=1 and key in ('26000000', '26000099', '26200020','26200029');</code>
| Ändert den Typ von Finanzpositionen. <code>potyp=2</code> steht für Einnahmen, <code>potyp=3</code> für Ausgaben. Die Einstellung gilt nur für die Sicht inklusive statistischer Fortschreibungen (<code>variante=1</code>).
|-
| GXSTAGE_TECH_FIPOS
| <code>key like '%/%'</code>
| Legt fest, wie technische Finanzpositionen erkannt werden. Die Unterscheidung zwischen Einnahme und Ausgabe erfolgt nach <code>potyp</code>. Die Einstellung gilt automatisch nur für die Sicht inklusive statistischer Fortschreibungen (<code>variante=1</code>).
|}

=Usern Rechte auf Finanzstellen oder HHProgramme geben=

Standardmäßig ist im GX-Stage-Modul vorgesehen, Benutzerinnen und Benutzern Rechte auf Finanzstellen und Haushaltsprogramme zu geben. Die Universität Hohenheim nutzt zusätzlich eine Erweiterung, mit der auch Rechte auf Finanzpositionen und Fonds unterstützt werden.

Melden Sie sich als Administrator/-in an und öffnen Sie '''Kaufmännische Auswertungen -> Administration Kaufmännische Auswertungen'''.

[[Bild:GX-Stage-Modul-Konfiguration-Admin_gxstage1.png|600px]]

Wählen Sie anschließend den Punkt '''SAP Rechte administrieren'''.

[[Bild:GX-Stage-Modul-Konfiguration-Admin_gxstage3.png|600px]]

[[Bild:GX-Stage-Modul-Konfiguration-Admin_gxstage2.png|600px]]

Die Maske funktioniert ähnlich wie die Kernmodulmaske '''User suchen'''. Sie können nach einem User, nach einer Gruppe oder nach einer Finanzstelle bzw. einem Haushaltsprogramm suchen, für das bereits Berechtigungen vergeben wurden.

Nach dem Abschicken erscheinen die passenden Benutzerinnen und Benutzer.

[[Bild:GX-Stage-Modul-Konfiguration-Admin_gxstage4.png|600px]]

Klicken Sie beim gewünschten User auf einen der '''Bearbeiten'''-Buttons. Über '''Bearbeiten Auswahlfelder''' können Finanzstellen und Haushaltsprogramme über Auswahlfelder gepflegt werden. Über '''Bearbeiten Schlüsseleingabe''' können Schlüssel direkt eingetragen werden. Das ist bei bekannten Schlüsseln oft schneller.

{{Hinweis|Wenn nach der Schlüsseleingabe ein Eintrag ohne Bezeichnung erscheint, existiert die Finanzstelle oder das Haushaltsprogramm wahrscheinlich nicht oder der Schlüssel wurde falsch eingegeben. Löschen Sie den Eintrag dann über das rote X und erfassen Sie den korrekten Schlüssel erneut.}}

Im folgenden Beispiel erhält der User '''testfakab1''' Rechte für die gesamte Finanzstelle '''AB'''. Nach dem Klick auf Bearbeiten öffnet sich das Formular.

[[Bild:GX-Stage-Modul-Konfiguration-Admin_gxstage5.png|600px]]

Wählen Sie bei den Finanzstellen die Fakultät '''AB''' aus und klicken Sie auf den Einfüge-Button mit dem blauen Haken. Danach sieht der Dialog so aus:

[[Bild:GX-Stage-Modul-Konfiguration-Admin_gxstage5b.png|600px]]

Das Fenster kann anschließend geschlossen werden.

{{Achtung|In der Auswahlliste erscheinen sowohl Finanzstellen einschließlich TOP-Finanzstellen als auch Kostenstellen inklusive übergeordneter Hierarchie-Kostenstellen. Bei der Rechtevergabe ist wichtig, ob sich die spätere Auswertung auf die reguläre Finanzstellen-Sicht oder auf die organisatorische Sicht aus CO bezieht.}}

Wenn Sie einem User beispielsweise Rechte auf eine TOP-Finanzstelle '''1000''' geben, sieht der User in der regulären Finanzstellen-Sicht das Budget und alle Buchungen auf den untergeordneten Finanzstellen, z. B.:

<source lang="text">
1000
-1001
-1002
-1003
</source>

In der organisatorischen Sicht aus CO sieht der User in diesem Fall zunächst nichts, wenn dort die TOP-Finanzstelle '''1000''' nicht vorhanden ist. Dann müssen zusätzlich Rechte auf die einzelnen Kostenstellen, z. B. '''1001''', '''1002''' und '''1003''', oder auf eine übergeordnete Kostenstelle vergeben werden.

Wenn Sie einem User Rechte auf eine übergeordnete CO-Kostenstelle geben, z. B. '''8056_9000''', sieht er in der organisatorischen Sicht der Finanzstellen alles, was auf darunterliegenden Kosten- bzw. Finanzstellen gebucht wurde, z. B.:

<source lang="text">
8056_9000
-80569001
-80569002
-80569003
</source>

In der regulären Finanzstellen-Sicht sieht der User diese übergeordnete CO-Kostenstelle dagegen nicht, weil sie dort nicht existiert. In diesem Fall müssen zusätzliche Rechte auf die einzelnen Finanzstellen, z. B. '''80569001''', '''80569002''' und '''80569003''', oder auf eine vorhandene TOP-Finanzstelle vergeben werden.

User, die eine Finanzstelle sehen dürfen, dürfen automatisch alle Haushaltsprogramme sehen, die zu dieser Finanzstelle gehören. Eine Ausnahme gilt, wenn sie zu einer Gruppe mit exakt dem Namen '''SAP-Finanzstellen nur DummyHHProg''' gehören.

Soll ein User nur Rechte für ein bestimmtes Haushaltsprogramm erhalten, darf ihm nicht das Recht auf die gesamte Finanzstelle gegeben werden. Stattdessen wird nur das gewünschte Haushaltsprogramm zugeordnet. Im folgenden Beispiel erhält der User '''testfakab2''' nur Rechte für den '''Tag der offenen Tür'''.

[[Bild:GX-Stage-Modul-Konfiguration-Admin_gxstage6.png|600px]]

Klicken Sie wieder auf den blauen Haken unter dem Eintrag '''Tag der off. Tür'''. Danach sieht der Dialog so aus:

[[Bild:GX-Stage-Modul-Konfiguration-Admin_gxstage7.png|600px]]

Das Fenster kann anschließend geschlossen werden.

=Gruppen einrichten=

==Einfachste Variante==

Die einfachste Variante ist eine allgemeine Gruppe für dezentrale SAP-User. Öffnen Sie dazu unter '''Administration -> Benutzer''' den Menüpunkt '''Gruppe einrichten'''.

Die automatisch vergebene Gruppen-TID sollte unverändert bleiben. Im Beispiel ist dies die TID 14.

[[Bild:GX-Stage-Modul-Konfiguration-Admin_gxstage_gruppe1.png|600px]]

Geben Sie einen passenden Gruppennamen ein, z. B. '''dezentrale SAP-User'''. Bei '''Mitglieder''' wählen Sie die gewünschten Userkennungen aus. Alternativ können Sie später über '''Administration -> Benutzer -> User suchen''' einen Benutzer suchen, auf '''Bearbeiten''' klicken und ihn dort der Gruppe hinzufügen.

Diese einfache Variante funktioniert, hat aber drei Einschränkungen:

* Benutzer, die nur Rechte auf einzelne Haushaltsprogramme und keine Rechte auf komplette Finanzstellen haben, bekommen trotzdem den Bericht '''SAP-Budget nach Finanzstellen''' angeboten. Da die Auswahl einer Finanzstelle dort obligatorisch ist, können sie mit diesem Bericht nicht sinnvoll arbeiten.
* Sie müssen entscheiden, ob das Feld '''Finanzpositionswahl''' mit der Auswahl '''nur zahlungswirksam / alle inkl. stat. Fipos''' angezeigt werden soll.
* Wenn Standarduser den Finanzpositionsbericht öffnen, könnten sie beim Button '''Finanzposition''' zur Sicht '''inkl. Stat. Fortschreibung''' wechseln. Diese Möglichkeit sollte normalen Usern besser nicht angeboten werden.

Sie können diese einfache Gruppe daher auch als Expertengruppe verwenden, z. B. mit dem Namen '''SAP-Experten''', wenn die Mitglieder auch statistische Fortschreibungen bei Finanzpositionen sehen sollen.

==Gruppe für normale Finanzstellenberechtigte==

Für normale Finanzstellenberechtigte empfiehlt sich eine eigene Gruppe mit gezielten Maskenrechten und Sichtrechten.

===Gruppe einrichten===

Öffnen Sie unter '''Administration -> Benutzer''' den Menüpunkt '''Gruppe einrichten'''.

[[Bild:GX-Stage-Modul-Konfiguration-Admin_gxstage_gruppe6.png|600px]]

Lassen Sie die automatisch vergebene Gruppen-TID unverändert. Im Beispiel ist dies die TID 16. Als Gruppennamen können Sie z. B. '''SAP-Finanzstellenberechtigte''' verwenden.

Bei '''Mitglieder''' wählen Sie die Userkennungen aus. Alternativ können Benutzer später über '''Administration -> Benutzer -> User suchen''' gesucht, bearbeitet und der Gruppe hinzugefügt werden.

Bei '''Masken-Rechte''' wählen Sie folgende Berichte aus:

* 33000
* 33060
* 33080
* 33100

===Rechte auf Sichten===

Zusätzlich benötigt die Gruppe Rechte auf die relevanten SAP-Sichten. Öffnen Sie dazu '''Administration -> Masken -> Sicht suchen'''.

[[Bild:GX-Stage-Modul-Konfiguration-Admin_gxstage_gruppe3.png|600px]]

Wählen Sie zunächst die '''SAP-Finanzpositions-Sicht''' aus und klicken Sie auf '''Abschicken'''.

[[Bild:GX-Stage-Modul-Konfiguration-Admin_gxstage_gruppe4.png|600px]]

Klicken Sie in der ersten Zeile in der letzten Spalte auf das Symbol für '''User- und Gruppenrechte bearbeiten'''. Es öffnet sich ein umfangreicher Bearbeiten-Dialog für die Sicht.

[[Bild:GX-Stage-Modul-Konfiguration-Sicht_fipos.png|600px]]

Wählen Sie bei '''Gruppen, die diese Sicht sehen dürfen''' die Gruppe '''SAP-Finanzstellenberechtigte''' aus und klicken Sie auf '''neue Gruppe einfügen'''. Ein erneutes Speichern oder ein Leeren des Manager-Caches ist bei dieser speziellen Funktion nicht nötig.

Gehen Sie anschließend zurück zur Maske '''Sicht suchen''' und vergeben Sie Rechte für folgende Sichten bzw. Sichtarten:

* SAP-Finanzstellen-Sicht
* SAP-Geldgeber-Sicht
* SAP-Projekt-Sicht
* SAP-Zahlungspartner-Sicht

Wählen Sie jeweils die passende Sichtart aus.

[[Bild:GX-Stage-Modul-Konfiguration-sicht2.png|600px]]

Klicken Sie wieder in der ersten Zeile auf den Link für '''User- und Gruppenrechte'''.

[[Bild:GX-Stage-Modul-Konfiguration-sicht3.png|600px]]

Im Bearbeiten-Dialog scrollen Sie ganz nach unten.

[[Bild:GX-Stage-Modul-Konfiguration-sicht4.png|600px]]

Wählen Sie bei '''Gruppen, die die ganze Sichtart sehen dürfen''' die Gruppe '''SAP-Finanzstellenberechtigte''' aus und klicken Sie auf '''neue Gruppe einfügen'''. Auch hier ist kein erneutes Speichern und kein Leeren des Manager-Caches nötig.

Wiederholen Sie dieses Vorgehen für die oben genannten Sichtarten.

===Finanzpositionswahl ausblenden===

Standarduser sollten keine Möglichkeit haben, Werte inklusive statistischer Finanzpositionen auszuwerten. Deshalb sollte das Feld '''Finanzpositionswahl''' für die normale Gruppe ausgeblendet werden.

Öffnen Sie die Maske '''Administration -> Tabelle suchen''' und geben Sie als Stichwort '''pref''' ein. Es erscheinen ein Listen- und ein Detailformular für die entsprechende Tabelle.

[[Bild:GX-Stage-Modul-Konfiguration-verstecken1.png|600px]]

Klicken Sie bei '''group_field_pref_list''' in der zweiten Zeile auf den Bearbeiten-Button. Es öffnet sich ein Formular.

[[Bild:GX-Stage-Modul-Konfiguration-verstecken2.png|600px]]

Wählen Sie die Gruppe aus und anschließend das Feld '''33025 Finanzpositionswahl'''. Klicken Sie danach auf den gelben Einfüge-Button. Der neue Eintrag wird gespeichert.

[[Bild:GX-Stage-Modul-Konfiguration-verstecken3.png|600px]]

Klicken Sie danach auf den Detail-Bearbeiten-Button. Im Detailformular wählen Sie bei '''Voreinstellung''' den Wert '''versteckt''' und speichern die Änderung.

[[Bild:GX-Stage-Modul-Konfiguration-verstecken4.png|600px]]

Das Fenster kann anschließend geschlossen werden. Das vorherige Formular sieht danach so aus:

[[Bild:GX-Stage-Modul-Konfiguration-verstecken5.png|600px]]

Klicken Sie erneut den Einfüge-Button an und wiederholen Sie das Vorgehen für folgende Felder:

* 33068 Finanzpositionswahl
* 33107 Finanzpositionswahl

Nach der Änderung sollte der SuperX-Manager-Cache aktualisiert werden. Klicken Sie dazu oben rechts auf '''SuperX Manager'''.

[[Bild:GX-Stage-Modul-Konfiguration-manager1.png|600px]]

Klicken Sie anschließend auf '''Server-Cache aktualisieren'''.

[[Bild:GX-Stage-Modul-Konfiguration-manager2.png|600px]]

==Spezielle Gruppe nur für HHProgramm-Nutzer==

Für User, die mindestens eine Finanzstelle komplett sehen dürfen, kann die Gruppe wie unter [[Modul_GXStage_Konfigurationshandbuch#Gruppe für normale Finanzstellenberechtigte|Gruppe für normale Finanzstellenberechtigte]] eingerichtet werden.

Wenn Benutzer keine Rechte auf komplette Finanzstellen haben, sondern nur auf einzelne Haushaltsprogramme, sollte eine eigene Gruppe eingerichtet werden. Diese Gruppe bekommt den Bericht '''SAP-Budget nach Finanzstelle''' nicht angeboten.

Öffnen Sie unter '''Administration -> Benutzer''' den Menüpunkt '''Gruppe einrichten'''. Lassen Sie die automatisch vergebene Gruppen-TID unverändert. Im Beispiel ist dies die TID 15.

[[Bild:GX-Stage-Modul-Konfiguration-Admin_gxstage_gruppe2.png|600px]]

Geben Sie einen Gruppennamen ein, z. B. '''SAP-User nur HHprog'''. Bei '''Mitglieder''' wählen Sie die gewünschten Userkennungen aus. Alternativ können Sie später über '''Administration -> Benutzer -> User suchen''' einen Benutzer suchen, bearbeiten und der Gruppe hinzufügen.

Bei '''Masken-Rechte''' wählen Sie folgende Berichte aus:

* 33000
* 33080
* 33100

Anschließend müssen Sie der Gruppe noch Rechte auf SAP-Sichten geben. Gehen Sie dabei wie unter [[Modul_GXStage_Konfigurationshandbuch#Rechte auf Sichten|Rechte auf Sichten]] beschrieben vor, wählen Sie aber die Gruppe '''SAP-User nur HHProg''' aus.

Um die Finanzpositionswahl auszublenden, gehen Sie wie unter [[Modul_GXStage_Konfigurationshandbuch#Finanzpositionswahl ausblenden|Finanzpositionswahl ausblenden]] beschrieben vor.

Wenn Sie die Konfiguration testen, geben Sie dem User zusätzlich Rechte auf einzelne Haushaltsprogramme, wie unter [[Modul_GXStage_Konfigurationshandbuch#Usern Rechte auf Finanzstellen oder HHProgramme geben|Usern Rechte auf Finanzstellen oder HHProgramme geben]] beschrieben.

Wenn sich die Rechtezuordnung ändert, sollte die Gruppenzugehörigkeit zu dieser speziellen Gruppe entfernt und der User der passenden Gruppe zugeordnet werden.

==Gruppen für User mit statistischen Finanzpositionen==

Für User, die als Expertinnen und Experten auch Finanzpositionen mit statistischer Fortschreibung auswerten können sollen, kann eine Gruppe wie unter [[Modul_GXStage_Konfigurationshandbuch#Einfachste Variante|Einfachste Variante]] angelegt werden.

==Gruppe für User, die bei Finanzstellen nur das Dummy-HHProg sehen sollen==

Legen Sie für diesen Fall eine Gruppe mit exakt folgendem Namen an:

<source lang="text">
SAP-Finanzstellen nur DummyHHProg
</source>

Das Vorgehen entspricht der Einrichtung unter [[Modul_GXStage_Konfigurationshandbuch#Gruppe für normale Finanzstellenberechtigte|Gruppe für normale Finanzstellenberechtigte]]. Anhand des Gruppennamens erkennt das System, dass nicht wie üblich alle Haushaltsprogramme der gewählten Finanzstelle angezeigt werden sollen, sondern nur das Dummy-Haushaltsprogramm.

Wenn ein User für einige Finanzstellen alle Haushaltsprogramme sehen soll und für andere nur das Dummy-HHProgramm, müssen zwei Benutzerkennungen angelegt werden. Eine Kennung wird der Gruppe für normale Finanzstellenberechtigte zugeordnet, die andere der Gruppe '''SAP-Finanzstellen nur DummyHHProg'''.

Berichtsdesign mit JasperReports

2026-07-06T08:40:04Z

Andrek:

Berichtsdesign mit JasperReports

von Daniel Quathamer & Andre Knieschewski


= JasperReports installieren und konfigurieren =


== Voraussetzungen ==

* Jasperreports ist eine Laufzeitumgebung fürs Reporting, die in java-basierte Reporting Software integriert werden kann. Der Download ist hier: https://sourceforge.net/projects/jasperreports/. Dieses Paket enthält kommandozeilenbasierte Demos und die benötigten Libraries. Die Demos sind sehr nützlich und als Referenz gut nutzbar.
* Die Entwicklungsumgebung für JasperReports heißt "Jaspersoft Studio" und kann bezogen werden von https://community.jaspersoft.com/project/jaspersoft-studio. Es enthält auch obige Laufzeitumgebung. 
Da es ein Eclipse Plugin ist, können Sie es auch direkt in Ihrem Eclipse installieren (Menü Help → Eclipse Marketplace → Suchwort "Jaspersoft". Dort können Sie aber nur die jeweils aktuelle Version installieren.

Da der Download bei Jaspersoft nun nur für registrierte Nutzer zur Verfügung steht, hier noch ein Link für den Download: https://sourceforge.net/projects/jasperstudio/files/

* Für altere Projekte wurde auch iReport verwendet. Da es ein paar Bugs in den verschiedenen Versionen gibt, empfehlen wir zu der Erstellung von JasperReport Berichten die iReport Version 4.1.3, auch wenn in Edustore die Version 5.1.0 verwendet wird. Download der passenden Version von iReport von http://sourceforge.net/projects/ireport (dort auf "files"->"iReport" klicken, dann erhalten Sie Links auf die jeweilige Version.
* Für Demos & Deployment auch Apache ANT http://ant.apache.org/
* Java 1.8 JRE oder höher


== JasperReports und Jaspersoft Studio ==

JasperReports ist das Programm, das fertige Berichte erzeugen kann. Es besitzt (außer einer Vorschauansicht der Berichte) keine graphische Oberfläche. Für das Entwerfen von Berichten ist ''''''Jaspersoft Studio'''''' geeignet. Um es noch ein wenig zu veranschaulichen könnte man sagen, dass wenn ein JasperReport das Worddokument wäre, dann wäre Jaspersoft Studio z.B. Microsoft Word.


=== Jaspersoft Studio ===

Nach dem Download benötigen Sie Java 1.8 oder höher zum Ausführen. Nach dem Entpacken können Sie die Anwendung direkt starten.

Bei JasperSoft Studio wird als Grundlage Eclipse verwendet. Wenn man JasperSoft Studio herunter lädt, erhält man automatisch Eclipse mit dabei. JasperSoft Studio kann [http://community.jaspersoft.com/project/jaspersoft-studio hier] heruntergeladen werden.

Wenn lieber ein bereits vorhandenes Eclipse verwendet werden soll und Jaspersoft Studio dort als Plugin installiert werden soll, gibt es 2 Wege:

<ol style="list-style-type: decimal;">
<li>Unter Help → Eclipse Marketplace kann nach „Jaspersoft“ gesucht werden und das Plugin installiert werden
[[Datei:JasperReports-Handbuch_jaspersoftstudio_plugin_install1.png]]</li>
<li>Man kann auch über die Marketplace Webseite von Eclipse das Plugin Jaspersoft Studio suchen und das Icon per Drag&Drop nach Eclipse ziehen. Dann wird das Plugin automatisch installiert. [https://marketplace.eclipse.org/content/jaspersoft-studio Hier] die Webseite. (Bei mir hat das Drag&Drop leider nicht funktioniert. Das kann an Linux liegen. Unter Windows wird es sicherlich funktionieren.)</li></ol>


==== Jaspersoft Studio Einstellungen ====

Unter Windows - > Preferences → Jaspersoft Studio können Sie verschiedene Einstellungen vornehmen. Wichtig in der Menüpunkt "Compatibility": wählen Sie dort die JR-Version, die auch Ihre Ziel-Platform enthält.

Im Dateimanager von JasperSoft Studio gibt es Eclipse-typisch ein "virtuelles" Dateisystem mit dem Standardnamen "MyReports", zumindest beim Speichern von Dateien. Dieses Dateisystem liegt physisch im Ordner <<Home-Verzeichnis>>/JaspersoftWorkspace/MyReports.

Beim Öffnen von Dateien können Sie direkt mit "Open File" aufs normale Dateisystem zugreifen.


==== Jaspersoft Studio Entwurfsbereich ====

Hier eine Übersicht des Entwurfsbereichs, in rot finden Sie Erläuterungen:

[[Datei:JasperReports-Handbuch_jaspersoft_designer.png]]

Die Unterfenster können Sie Eclipse-typisch beliebig anordnen. Oben ein Beispiel.


===== Jaspersoft Studio Sortierung und Filterung der Datenquelle =====

Wenn die Datenquelle definiert ist, kann /sollte der Bericht die Sortierung und Filterung der Daten festlegen. Dies ist etwas versteckt im Designer mittig oberhalb des Entwurfsbereichs:

[[Datei:JasperReports-Handbuch_jaspersoft_design_query.png]]

Im "Dataset and Query Dialog" sind die Felder der Datenquelle aufgeführt. Unten finden Sie die Reiter "Sorting" und "Filter Expression". Dort pflegen Sie beides.


===== Jaspersoft Studio Berichtsdesign und Vorschau =====

Im Designmodus können Sie den Bericht entwerfen, oder den XML-Quellcode. Beim Klick auf den Reiter "Preview" bekommen Sie eine Vorschau des Berichts:

[[Datei:JasperReports-Handbuch_jaspersoft_design_preview.png]]

Oberhalb der Vorschau können Sie die Datenquelle (d.h. den "Data Adapter" angeben, und rechts daneben die Anwendung, die den Bericht zur Anzeige bringt ("Viewer"). Voreingestellt ist hier der Java-interne Viewer von JasperReports, Sie können den aber umstellen z.B: auf PDF oder Excel.

Mit Klick auf das grüne Dreieck führen Sie den Bericht aus und erhalten die Vorschau.

<blockquote>Achtung: Es ist aufgefallen, dass beispielsweise Fettdruck in der PDF-Vorschau nicht angezeigt wird. Im Java-Preview und aus der Weboberfläche geladen, ist der Fettdruck ersichtlich.
</blockquote>

===== Jaspersoft Studio Berichtsstruktur =====

Im "Outline View" sehen Sie die Struktur des Berichts, d.h. aktive "Bänder" und Metadaten:

[[Datei:JasperReports-Handbuch_jaspersoft_design_outline.png]]

Die Elemente unter "Fields" werden bei Nutzung in [[Berichtsdesign_mit_JasperReports#Template erzeugen|Edustore]] automatisch gefüllt. Alles weitere definieren Sie.


===== Jaspersoft Studio Elemente bearbeiten =====

Wenn Sie im Design Modus ein Element markieren, wird es automatisch im Outline und in dem Reiter "Properties" selektiert:

[[Datei:JasperReports-Handbuch_jaspersoft_design_properties.png]]

Im Outline zeigt es lediglich, wo es sich befindet, und im Reiter "Properties" können Sie Formatierung, Anzeige etc. bearbeiten.


=== iReport ===

[[Datei:JasperReports-Handbuch_welcome.png]] Das Paket enthält bereits die Laufzeitumgebung JasperReports, diese muss also nicht separat installiert werden. Nichtsdestotrotz empfiehlt sich der Download, denn in dem JasperReports-Paket befinden sich viele lehrreiche Demo-Berichte.

Die Windows-Version beinhaltet auch einen Installer. Um diesen zu nutzen sind Admin-Rechte erforderlich.

Alternativ bzw. unter Linux ist iReport ohne Installation direkt nach dem Entpacken lauffähig. Wenn Sie auch Scriptlets erstellen wollen, müssen Sie nicht nur eine Java-Laufzeitumgebung (JRE) installieren, sondern ein JDK, und die Datei $JAVA_HOME/lib/tools.jar nach iReport-<<Versionsnr.>>/ireport/libs kopieren. Danach müssen Sie iReport neu starten.

Start unter Windows: iReport-<<Versionsnr.>>/bin/ireport.exe

Start unter Linux: iReport-<<Versionsnr.>>/bin/ireport


==== iReport Einstellungen ====

Als erstes sollten Sie die Anwendungen einstellen, mit denen iReport generierte Berichte anzeigen soll:

Im Menü Extras-> Optionen wählen Sie im Reiter "iReport"-"Viewers" die entsprechenden Anwendungen:

[[Datei:JasperReports-Handbuch_ireport_viewers.png]]


==== iReport Entwurfsbereich ====

Der Entwurfsbereich bzw. "Designer" hat einen recht komplexen Aufbau. Sie können die Fenster und Seitenbereiche zwar recht flexibel anpassen, aber hier ist die Auslieferung:

[[Datei:JasperReports-Handbuch_designer_ueberblick.png]]

Die wichtigen Bereiche sind hervorgehoben:

* Berichtsstruktur: Welche Seitenbereiche gibt es?
* Datenquelle: Welche Datenbank wird genutzt?
* Abfrage: Was ist die konkrete Abfrage für den Bericht?
* Elemente: Welche Elemente kann ich einfügen, und welche Eigenschaften haben sie?
* Vorschau: wie sieht der Bericht "gedruckt" aus?
* Fehlerausgabe: Jeder Bericht wird "kompiliert", dazu gibt es eine Fehlerausgabe

Im Reiter "Preview" kann man sich eine Vorschau des Ausdrucks anzeigen lassen.


=== Unterschiede iReport und JasperSoft Studio ===

Mit der Version 5.5 wurde die Entwicklung von iReport eingestellt, die Firma JasperSoft empfiehlt seit dem die Benutzung von JasperSoft Studio. Nach unseren Erfahrungen ist die Arbeit mit iReport 4.1.3 (die letzte stabile Version) hier und da "leichtgewichtiger" und einfacher, ganz zu schweigen vom Overhead, den JasperSoft Studio mit Eclipse einbringt. Besonders nervig empfanden wir es, dass JasperSoft Studio anders als iReport verschiedene Objekteigenschaften in Reitern organisiert, und bei jedem Wechsel der Markierung eines Berichtselements muss man in JasperSoft Studio wieder zum richtigen Reiter wechseln.

Andererseits ist JasperSoft Studio kompatibel mit neueren JR-Möglichkeiten. Insbesondere bei dem Umgang mit Diagrammen gibt es in JasperSoft Studio erheblich mehr Möglichkeiten, z.B. Chart Customization. Außerdem ist es vorteilhaft, wenn Sie ohnehin Eclipse nutzen. Sie sollten für Ihre Arbeit also abwägen ob Sie die neueren Möglichkeiten im jeweiligen Bericht überhaupt brauchen, ggf. sind Sie mit iReport besser bedient. Aber das ist Geschmackssache.

<blockquote>Beachten Sie aber bitte: sobald Sie einen Bericht mit JasperSoft bearbeitet und gespeichert haben, ist er mit iReport 4.1.3 nicht mehr bearbeitbar, bzw. nur wenn Sie die [[Berichtsdesign_mit_JasperReports#UUID's|UUIDs]] entfernt haben.
</blockquote>
Beide Produkte befinden sich noch im Einsatz, daher hier nur ein paar Kapitel zur Handhabung der jew. Software.


==== Handhabung ====


===== Preview =====

Bei iReport waren die Buttons für Designer und Preview immer oben.

[[Datei:JasperReports-Handbuch_jss-ir_preview1.png]]

Bei Jaspersoft Studio liegen die Buttons unten:

[[Datei:JasperReports-Handbuch_jss-ir_preview2.png]]


===== Palette =====

Die Palette ist bei iReport und Jaspersoft Studio an gleicher Position zu finden.

Ireport:

[[Datei:JasperReports-Handbuch_jss-ir_palette1.png]]

Jaspersoft Studio:

[[Datei:JasperReports-Handbuch_jss-ir_palette2.png]]


===== Objekt-Eigenschaften =====

Die Objekt-Eigenschaften liegen auch an der gleichen Stelle, jedoch sind bei Jaspersoft Studio die Gruppierungen der Eigenschaften in Karteireiter unterteilt. Bei iReport ist es einfach eine lange Liste mit Unterteilungen.

iReport:

[[Datei:JasperReports-Handbuch_jss-ir_properties2.png]]

Jaspersoft Studio:

[[Datei:JasperReports-Handbuch_jss-ir_properties1.png]]


== JasperReports als Kommandozeilen-Tool ==

In der JasperReports-Distribution befindet sich ein ANT-Script, das mehrere Berichte erzeugen kann.

Beispiel xmldatasource:

<source lang="bash">
cd demo/samples
cd xmldatasource
ant -p
</source>

Die Ausgabe ist:

[[Datei:JasperReports-Handbuch_ant_xmldatasource.png]]

Es werden, je nach Auswahl pdf-, Excel- oder andere Berichte erzeugt. Mit dem Target "test" werden alle Targets durchlaufen.

<source lang="bash">
ant test
</source>

Achtung: manche Demos brauchen eine laufende HSQLDB (siehe demo/hsqldb).


= Datenquellen =

Allgemein unterstützt JasperReports verschiedene Datenquellen, z.B. relationale Datenbanken, Excel, CSV oder XML. Auch Webservices sind möglich. Speziell für SuperX/ HISinOne-BI gibt es spezielle Datenquellen-Vorgaben, damit Sie die Daten auch im Server-Betrieb nutzen können. Hier also nur die allgemeinen, also SupeRX/BI-unabhängigen Quellen, wenn Sie JasperReports am lokalen Arbeitsplatz nutzen.


== Datenquelle Datenbank ==

Eine relationale Datenbank ist in JasperSoft Studio als "Data Adapter" einzurichten. Oben links befindet sich der Dialog zum Erzeugen (1) des Data Adapter, und dann darunter die Zeile "Database Jdbc Connection" (2):

[[Datei:JasperReports-Handbuch_data_adapter1.png]]

Dort geben Sie dann die jdbc-spezifischen Daten an (Datenbanktyp, Name etc.).

<blockquote>Achtung: die Nutzung setzt eine direkte Datenbankverbindung zum DB-Server voraus, an vielen Unternehmenanwendungen wird dies nicht mehr erlaubt. Ggf. fragen Sie bei Ihren Systemadministrator/innen nach.
</blockquote>


== Datenquelle Excel-Datei ==

Eine Excel Datei ist in JasperSoft Studio als "Data Adapter" einzurichten. Hier ein Beispiel:

[[Datei:JasperReports-Handbuch_datenquelle_excel_1.png]]

Die Excel Datei hat vier Spalten und eine führende Zeile mit den Spaltenüberschriften. Achten Sie darauf, dass die Datentypen der Spalten in Excel dem Inhalt entsprechen. Hier die Spalten:

* Frage Nr.
* Text
* Mit_ohne_schule
* Summe

Aus der Excel-Datei erzeugen Sie einen "Data Adapter". Der Data Adapter vom Typ "Excel File" hat ein paar Eigenschaften:

[[Datei:JasperReports-Handbuch_datenquelle_excel_2.png]]

Danach können Sie in einem Berichtsdesign die Datenquelle definieren:

[[Datei:JasperReports-Handbuch_datenquelle_excel_5.png]]

Sie wählen dort oben links zunächst den "Data Adapter" aus (1), und klicken dann rechts auf "Read Fields" (2):

[[Datei:JasperReports-Handbuch_datenquelle_excel_3.png]]

Aus der Datenquelle werden dann die Datenfelder (3) und Inhalte (Reiter "Data preview") automatisch übernommen.


= Berichtsdesign =

Das Erstellen eines Berichtes erleichtert JasperReports wesentlich. Dennoch wird man sich damit etwas beschäftigen müssen, um ein vernünftiges Ergebnis zu erhalten.

Zuerst muss man den Bericht öffnen. Das geschieht über „Datei“ → „Open“ → Bericht auswählen → auf „Öffnen“ klicken. Nun noch oben links die für diesen Bericht erstellte Datenquelle auswählen und man kann loslegen.

JasperReports bezeichnet die Ausgabebereiche als Bänder. Ein Band ähnelt einer Zeile. Es reicht über die komplette Seitenbreite. Die Höhe kann dabei selbst bestimmt werden und wird dem Informationsgehalt angepasst. Das Band „Detail 1“ ist so etwas wie das Hauptband, in dem dann die Informationen zeilenweise ausgegeben werden. Es wird also eine Schleife über die Daten (Tabelle) ausgeführt und für jeden Datensatz ein mal das Detail Band ausgegeben. Die linke Spalte könnte z.B so aussehen:

[[Datei:JasperReports-Handbuch_iReport-iReport_Leiste_Neu.jpg]]

Hier sieht man, das das Band „Detail 1“ aktiv ist und die anderen wie „Title“ noch nicht. In den Gruppen „Fields“ und „Variablen“ befinden sich die Felder (Spalten) aus der Ergebnistabelle und interessante Variablen wie Seitenzahl, die man nun einfach in das bestehende Band „Detail 1“ per „Drag and Drop“ ziehen kann.

[[Datei:JasperReports-Handbuch_iReport-Feld_Name.jpg]]

Wenn man z.B. in der Gruppe Fields das Feld „Name“ hat und dies in das Band „Detail 1“ zieht,befindet sich ein Platzhalter im Entwurfsbereich:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_1_Namen.jpg]]

Wenn Sie dann auf „Preview“ klicken, wird eine Vorschau des Berichts angezeigt.

[[Datei:JasperReports-Handbuch_iReport-Designer_Preview.jpg]]

Es werden alle Namen aufgelistet, die in der Datenquelle vorhanden sind:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_1_Namen_Ergebnis.jpg]]

Sie können das Layout der Ausgabe (Schriftart, Größe) über die Eigenschaften des Feldes variieren.

Um wieder zurück in den Entwicklermodus zu kommen klickt man einfach wieder auf den Reiter "Designer".

Die Bänder „Title“, „Page“ usw. kann man mit einem Rechtsklick und dann „Add Band“ hinzufügen und auch wieder mit einem rechtsklick und dann „Delete Band“ wieder entfernen. Diese Bänder haben bestimmte Eigenschaften. Z.B. Band „Titel“ wird nur einmal auf der ersten Seite abgebildet, Band „Page Header/Footer“ auf jeder Seite am Anfang/Ende.


== Sortierung und Filtern ==

Normalerweise verarbeitet JasperReports die Datensätze zeilenweise in der Reihenfolge, in der sie bereitgestellt werden. Sie können im Entwurfsmodus die Sortierung bzw. Filterung der Datensätze anpassen:

[[Datei:JasperReports-Handbuch_ireport_sort1.png]]

Klicken Sie auf das Icon mit der Tonne und Sie gelangen in die Einstellungen für die Datenquelle.

[[Datei:JasperReports-Handbuch_ireport_sort2.png]]

Im Button Sortieren können Sie nach allen Feldern des Berichts aufsteigend bzw. absteigend sortieren.

[[Datei:JasperReports-Handbuch_ireport_sort3.png]]

Im Button "Filter expression" können Sie eine Formel definieren, um die Gültigkeit von Datensätzen zu definieren:

[[Datei:JasperReports-Handbuch_ireport_filter1.png]]

Z.B. die Expression ".contains("12") würde auf alle Datensätze filtern, die im Feld die Zeichenkette "12" enthalten. Weitere Infos im Kapitel zum [[Berichtsdesign_mit_JasperReports#Expression Editor|Expression Editor]].


== Listen ==

Listen lassen sich einfach erstellen, indem man die jeweiligen Felder ins Detail-Band zieht. Manchmal kann es vorkommen, dass Textfelder "überlaufen", d.h. die rechteckige Box, die das Feld markiert, ist zu klein für den Feldinhalt. Beispiel:

[[Datei:JasperReports-Handbuch_listen_stretch.png]]

In diesem Falle muss man das Attribut des jew. Felder (hier "Fächergruppe") "Text Field properties > Stretch with overflow" ankreuzen.

Achtung: wenn das Feld Teil einer tabellarischen Auflistung ist, muss man die anderen Element mit der Eigenschaft "Stretch type → Relative to tallest object" versehen, hier z.B. die Felder "Studienfeld" und "Studienbereich".

Bei vielen Zeilen ist es übersichtlicher, jede zweite Zeile farbig zu hinterlegen. Dieser Trick ist im Abschnitt Tabellengestaltung [[Berichtsdesign_mit_JasperReports#Zeilen alternierend einfärben|erläutert]].


== Gruppierung ==

Wichtige Vorbemerkung zum Gruppieren: JasperReports setzt bei der Gruppierung voraus, dass die Datensätze der Datenquelle nach den Gruppierungsmerkmalen sortiert sind. Alle Merkmale, nach denen Sie gruppieren, sollten also entweder direkt in der Datenquelle sortiert sein, oder in JasperReports im [[Berichtsdesign_mit_JasperReports#Sortierung und Filtern|Berichtsentwurf]].


=== Gruppen definieren ===

Zu den Standardbändern kann man nun auch noch selbst definierte Gruppen hinzufügen. Mit einem Rechtsklick auf den obersten Knoten → „Add Report Group“ öffnet sich ein Fenster in dem man der Gruppe einen Namen geben kann und das Objekt wählt für das die Gruppe erstellt wird.

[[Datei:JasperReports-Handbuch_designer_add_group.png]]

<blockquote>Achtung: wenn Sie mehrere Gruppierungsebenen benötigen, dann sollte die Reihenfolge des Hinzufügens der Gruppen "top-down" verlaufen, d.h. zuerst die oberste Gruppierung hinzufügen, dann die Gruppe darunter usw.
</blockquote>
In dem folgenden Beispiel wird die Gruppe „Monat“ gewählt und in dem nächsten Schritt mit Header und Footer hinzugefügt:

Man zieht das Feld „Namen“ in das Band „Detail“ und „Monat“ in das erstellte Band „Monat Group Header 1“. Aus der Palette rechts oben (wenn nicht vorhanden bekommt man es über „Fenster“ → „Palette“) zieht man einen „Static Text“ in das Band „Monat Group Header 1“ vor der Ausgabe des Monats, benennt das Feld „Monat:“ und noch eine Linie darunter. Zusammen sollte es so aussehen:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_Monat_Namen.jpg]]

Wenn man nun auf „Preview“ klickt erhält man als Ergebnis:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_Monat_Namen_Ergebnis.jpg]]


=== Seitenumbrüche ===

Damit eine Gruppe nicht durch einen Seitenumbruch auseinandergerissen wird, gibt es einige Einstellungen in dem Band der Gruppe. Dazu einfach auf das jeweilige Band klicken, für welches die Einstellungen vorgenommen werden sollen und dann in „Eigenschaften“ → „Group properties“ → „Keep Together“ anklicken oder wenn man möchte „Reprint header“ um den "Header" der Gruppe am Seitenkopf zu wiederholen.

Sie können auch angeben daß vor jedem Gruppierungswechsel ein Seitenumbruch ausgeführt wird:

[[Datei:JasperReports-Handbuch_designer_add_group_new_page.png]]

Mit "Start on a new page" wird eine neue Seite bei jedem Gruppenwechsel begonnen. Speziell beim Export nach Excel kann dies in Tandem mit Arbeitsblättern nutzen, siehe [[Berichtsdesign_mit_JasperReports#Excel-Export in einzelne Tabellenblätter|unten]].


=== Gruppensummen ===

Gruppensummen kann man im Kopf oder Fuß einer Gruppe anlegen. Sie aktivieren z.B. den Gruppenfuß im Report Inspector, und ziehen dann das Feld Summe in den Entwurfsbereich. Beim "Fallenlassen" werden Sie gefragt, ob Sie den jew. Wert oder eine Aggregatfunktion nutzen wollen. Für Zwischensummen wählen Sie "Sum":

[[Datei:JasperReports-Handbuch_designer_add_group_foot1.png]]

Im Entwurfsbereich setzen Sie noch ein Label bzw. "Static Text"-Element rechtsbündig davor, und setzen beide Elemente fett:

[[Datei:JasperReports-Handbuch_designer_add_group_foot2.png]]


=== Gruppierung ohne eigenes Band ===

Bei der Gruppierung in JasperReports wird in der Regel ein horizontales Band für die Gruppierungsebene angelegt. Das führt dazu, daß man zeilenorientiert gruppiert. In manchen Fällen kann es gewünscht sein, in den Spalten einer Tabelle zu gruppieren. Hier ein Beispiel für das Ziel:

[[Datei:JasperReports-Handbuch_gruppierung_spalten1_vorlage.png]]

In dem Beispiel wird in den Zeilen nach dem Merkmal '''Fach''' gruppiert. Zusätzlich wird noch in den Spalten nach Fachsemestern gruppiert. Um dieses Layout zu realisieren, muss man wie folgt vorgehen:

Erzeugen Sie ein Column Header Band, und ein Group Footer-Band für die Gruppierungsebene Fach. Warum Group Footer? Weil innerhalb des Fachs nochmal gruppiert werden soll, und daher erst nach dem Gruppieren nach Fach nach Fachsemestern gruppiert wird. Ein Detail-Band gibt es hier nicht.

[[Datei:JasperReports-Handbuch_gruppierung_spalten3_band.png]]

Erzeugen Sie eine neue Variable z.B. mit dem Namen "fs1" für erstes Fachsemester, und geben Sie der Variable folgende Eigenschaften:

[[Datei:JasperReports-Handbuch_gruppierung_spalten2_variable_1fs.png]]

Zur Erläuterung: Die Variable filtert die Datensätze gemäß dem Ausdruck in Variable Expression, und tut dies auf der Gruppierungsebene "fach". Die Variable Expression ist eine für unsere Zwecke sehr nützliche Java-Kurzfassung einer IF-THEN-Bedingung, und meint:

<blockquote>Wenn der Inhalt des Feldes "Anzahl Fachsemester" gleich 1 ist, dann gib die Summe der jew. Studierenden aus, wenn nicht, dann gib 0 aus.
</blockquote>
Analog kann man noch die Variable "fsgr13" für "Fachsemester > 13" anlegen.

Danach kann man die Variablen "fs1" und "fsgr13" in das Band "Fach Group Footer 1" ziehen, und noch das Feld "Summe" für die Gesamtsumme. Dann tragen wir im Column Header Band noch die Spaltenüberschriften ein. Insgesamt sieht Berichtsentwurf dann so aus:

[[Datei:JasperReports-Handbuch_gruppierung_spalten4_band.png]]

Und das Ergebnis sieht so aus:

[[Datei:JasperReports-Handbuch_gruppierung_spalten5_band.png]]

Fertig. Man könnte nun noch weitere Fachsemester-Intervalle einfügen, oder z.B. eine Summe der Studierenden in der Regelstudienzeit.


=== Gruppierung mit virtuellen Dimensionen ===

Wenn Sie nach Feldern gruppieren wollen, die es in Ihrer Datenquelle gar nicht gibt (z.B. nach Aggregationen von Mekrmalskombinationen), dann können Sie auch Variablen mit speziellen Formeln anlegen, und diese dann in die Gruppierung aufnehmen.

<blockquote>Wichtig: Wenn die Gruppierungsvariable nicht im Summary Band genutzt wird, muss der resettype der Variable auf „None“ gesetzt werden.
</blockquote>
Im Abschnitt zu [[Berichtsdesign_mit_JasperReports#Kreuztabellen mit virtuellen Dimensionen|Kreuztabellen]] wird z.B. gezeigt, wie die Fächer Mathe, Physik und Biologie in einen neuen Wert "Naturwissenschaften" transformiert werden.


=== Variablen und Gruppierung ===

Beim Anlegen von Gruppen-Bändern und beim Ziehen von Feldern in das jew. Gruppenband legt JR automatisch eine Variable an, mit der jew. Aggregationsfunktion. Diese Variable hat folgende Eigenschaften:

Expression: das Feld, aus dem die Variable gespeist wird

Calculation: Die Aggregatfunktion, z.B. "sum"

Reset Type: Die Gruppierungsebene

Wenn Sie die Variable in Textfeldern des Gruppenbandes nutzen, gibt sie jeweils den richtigen Wert an, egal ob Gruppenkopf oder Fuß.

Wenn Sie aber mit "Print-when-Expressions" im Gruppenband arbeiten und auf die Variablen zugreifen, funktionieren diese standardmäßig nur im Gruppenfuß, weil erst am Ende der Gruppe der Wert bekannt ist. In diesem Fall müssen Sie der Variable auch eine "Initial Value Expression" mit dem jew. Feld geben.


=== Berechnungen auf Gruppenebene ===

Wenn Sie auf der Gruppenebene Berechnungen, z.B. Mittelwerte, durchführen wollen, gibt es einige Fallstricke:

* Die in JR eingebauten Funktionen wie "avg" arbeiten auf Gruppenebene nicht immer exakt.
* Komplexere Formeln auf Gruppenebene in Variablen abzubilden und diese dann das Quelle für Textfelder zu nehmen hat bei uns nicht geklappt.

Hier unser Vorgehen:

* Definieren Sie auf der Ebene der jew. Gruppe eine Variable mit der Gesamtsumme, und eine mit der Summe der zu mittelnden Werte. Diese Variablen haben als "reset Type" die jew. Gruppierungsebene.
* Im Textfeld, das Sie ausgeben, verwenden Sie dann die Berechnungsformel, z.B. einen Quotienten. Verwenden Sie für die Berechnung nicht eine neue Variable, sondern fügen Sie die Formel direkt in das Textfeld ein.

Im folgenden ein Beispiel: Wir haben eine Absolventenliste pro Studiengang und Semester, darin werden dann Mittelwerte von Abschlussnoten gebildet. Die Datenquelle hat summierte Zeilen pro Note:

[[Datei:JasperReports-Handbuch_notenschnitt_daten.png]]

Im obigen Beispiel haben wir in der Zeile 5 eine Absolventin mit der Note 1,1. In der letzten Zeile haben wir zwei Absolventinnen mit der Note 1,2.

Würden wir den Notenschnitt manuell berechnen, müßten wir die Notensumme (Spalte H*K) ermitteln, hier wäre der Wert 32,3. Die Summe der Absolventen in Spalte K wäre 16, d.h. der Notenschnitt wäre 32,3/16 = 2,02.

In JasperReports wäre der Entwurf wie folgt:

[[Datei:JasperReports-Handbuch_notenschnitt_design1.png]]

Wir haben eine Variable "Summe_1" auf der Ebene des Semester-Bandes, die im obigen Excel der Summe der Spalte "Summe" entspricht.

Außerdem haben wir eine Variable "Notensumme" mit der Formel $F{Note}*$F{Summe}, auf der Ebene der Gruppe "Semester". Achten Sie drauf, dass Sie als Typ "java.lang.Double" nehmen, damit Sie keine Rundungsfehler bekommen.

Der Quotient wird dann im Textfeld gebildet, das den Notenschnitt auf Semesterebene enthält, und auf zwei Nachkommastellen gerundet:

[[Datei:JasperReports-Handbuch_notenschnitt_design2.png]]

Das Textfeld selbst muss bei "Evaluation time" den Wert "Group" haben, und bei "Evaluation group" dann den Wert der Gruppe "Semester". Und hier das Ergebnis in der Vorschau:

[[Datei:JasperReports-Handbuch_notenschnitt_vorschau.png]]

Der Wert 2,02 stimmt mit unserer manuellen Berechnung überein.


== Tabellengestaltung ==


=== Summen, Seitenzahlen ===

Um es noch ein wenig interessanter zu gestalten fügt man noch das Gehalt hinzu, summiert es für die Monate und gesamt. Dazu noch die Seitenanzahl und einen Seitenzähler und eine Überschrift.

Das Gehalt bekommt man, indem man das Gehalt aus den Feldern neben den Namen zieht. Das selbe macht man auch nochmal in das Band „Monat Group Footer 1“ und wählt hier die Aggregation „Sum“ aus, um die Summe zu erhalten.

Um einen Seitenzähler zu erhalten fügt man zunächst das Band „Page Footer“ hinzu und legt dort die Variable „PAGE_NUMBER“ ab.

[[Datei:JasperReports-Handbuch_iReport-Page_Number.jpg]]

Unter „Eigenschaften“ → „Text field properties“ → „Evaluation Time“ wählt man hier „Now“ um die aktuelle Seitenanzahl zu bekommen und „Report“ um die gesamte Seitenanzahl zu erhalten. In dem Beispiel ist die Ausgabe z.B.: „Seite 2 von 6“.


=== Seitenumbrüche steuern ===

Damit die drei Personen im Monat 2 nicht durch einen Seitenumbruch auseinandergerissen werden, gibt es einige Einstellungen in dem Band der Gruppe. Dazu einfach auf das jeweilige Band klicken, für welches die Einstellungen vorgenommen werden sollen (hier „Monat“) und dann in „Eigenschaften“ → „Group properties“ → „Keep Together“ anklicken oder wenn man möchte „Reprint header“ um den "Header" der Gruppe am Seitenkopf zu wiederholen.

Beispiel im Designermodus:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_2_Monat_Namen.jpg]]

Beispiel im Preview:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_2_1_Monat_Namen_Ergebnis.jpg]]

[[Datei:JasperReports-Handbuch_iReport-Beispiel_2_2_Monat_Namen_Ergebnis.jpg]]


=== Zeilen alternierend einfärben ===

Um nun bei mehreren Datensätzen auch noch den Überblick in den Zeilen zu behalten kann man jetzt auch noch den Hintergrund der Zeile abwechselnd farbig gestalten. Dazu Zieht man aus den „Reports Elements“ das „Rectangle“ in das „Detail 1“ Band

[[Datei:JasperReports-Handbuch_iReport-Even_Odd_2.jpg]]

und passt es der Größe des Bandes an.

[[Datei:JasperReports-Handbuch_iReport-Even_Odd_1.jpg]]

Die Hintergrundfarbe kann man nun in den Eigenschaften in „Backcolor“ ändern. Damit dies nun nicht in jeder Zeile erscheint, sondern abwechselnd, fügt man noch in den Eigenschaften in „Print When Expression“ den Wert Boolean.valueOf( $V{PAGE_COUNT}.intValue() % 2 == 0 ) ein.

Zur erläuterung:

Die Variable „PAGE_COUNT“ zählt die Anzahl der Datensätze hoch. Mit „% 2“ wird diese Variable durch 2 geteilt und nur der Restwert ausgegeben. Als Ergebnis erhält man also in jeder ungeraden Zeile eine 1. Dieses Ergebnis wird nun mit der „0“ verglichen. Wenn dieser Ausdruck/Vergleich (expression) wahr ist, wird das Objekt, in diesem Fall der Hintergrund, angezeigt. Bei diesem Ausdruck erhält also jede gerade Zeile den Hintergrund. Möchte man lieber die ungeraden Zeilen hervorheben, schreibt man einfach eine 1 anstelle der 0 hinter „==“.

[[Datei:JasperReports-Handbuch_iReport-Even_Odd_3.jpg]]

Das Ergebnis bei einer ungeraden Hervorhebung sieht z.B. so aus:

[[Datei:JasperReports-Handbuch_iReport-Even_Odd_4.jpg]]

Ein weiteres Beispiel welches bereits in der Uni Mannheim benutzt wird ist die Ausgabe einer Rechnungslegungsliste. Das Beispiel zeigt nicht nur ein aufwändigeres Layout, sondern auch, wie man gruppierte Tabellen anlegt: Dabei sind die Zeilen der Tabelle im Detail 1 Band, und die Zwischensummen in den Gruppierungs-Bändern. Die Spaltenüberschriften der Tabelle befinden sich im untersten Group-Header-Band. Im Designermodus sieht das ganze folgendermaßen aus:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_3_Uma.jpg]]

Und im Preview:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_3_Uma_Ergebnis_1.jpg]]

[[Datei:JasperReports-Handbuch_iReport-Beispiel_3_Uma_Ergebnis_2.jpg]]


=== Rahmenlinien '''vorausschauend setzen''' ===

Sowohl bei Text- als auch bei Static-Fields findet sich ein eigener Reiter zum setzen von Rahmeneigenschaften. Dort wird der Abstand des Inhaltes zum Rahmen des jeweiligen Feldes definiert, sowie Rahmenlinien gesetzt.

Beim Setzen von Rahmenlinien wird empfohlen, dass bei nebeneinanderliegenden Feldern, welche durch eine Rahmenlinie getrennt werden, jeweils in beiden Feldern Rahmenlinien gesetzt werden und nicht nur in einem der beiden Felder. Denn beim Export in das PDF-Format ist ersichtlich ob nur eines der Felder oder beide Felder Rahmenlinien besitzen. Falls dies also nicht einheitlich umgesetzt wird, erscheinen Rahmenlinien an entsprechenden Stellen dünner beziehungsweise dicker (bei Excel-Dokumenten tritt dieser Effekt nicht auf):

[[Datei:JasperReports-Handbuch_borders2.png]]


== Unterberichte ==

<blockquote>Achtung: In Edustore funktionieren Unterberichte nur, wenn der Dateiname der jrxml-Datei mit "_xmlsource.jrxml" endet. Dadurch wird dem Servlet mitgeteilt, dass die Datenquelle für den Bericht ein XML-Datenstrom ist. Dabei ist mit Performanceeinbußen zu rechnen. 
Außerdem muss beim Berichtsdesign die gleiche JasperReports Version genutzt werden wie im Server.
</blockquote>
Im folgenden eine Anleitung zur Erstellung eines Unterberichts:


=== Konfiguration des Hauptberichts ===

Erzeugen Sie für den Unterbericht mit Hilfe des [[Berichtsdesign_mit_JasperReports#Template erzeugen|Template-Generators]] in Edustore einen leeren Bericht, und speichern Sie diesen am besten im gleichen Verzeichnis wie den Hauptbericht.

Ziehen Sie dann das Subreport-Werkzeug in den Entwurfsbereich:

Ggf.

[[Datei:JasperReports-Handbuch_subreport0_tool.png]]

Es startet der Subreport-Assistent. Hier geben Sie zunächst den Dateinamen oben an:

[[Datei:JasperReports-Handbuch_subreport1_wizard1.png]]

Im nächsten Schritt geben Sie eine Datenbank-Verbindung an. Hier wählen Sie "Don't use any connection...":

[[Datei:JasperReports-Handbuch_subreport1_wizard2.png]]

Im nächsten Schritt werden Parameter angezeigt, zu diesem Zeitpunkt gibt es aber noch keine.

[[Datei:JasperReports-Handbuch_subreport1_wizard3.png]]

Klicken Sie einfach auf "Weiter". Sie werden dann aufgefordert, einen Dateipfad für den Unterbericht zu vergeben. IReport legt diesen standardmäßig in das gleiche Verzeichnis wie den Hauptbericht. Für Edustore sollten Sie dies auch tun.

Bitte beachten Sie dass Sie beim Unterbericht nicht die *.jrxml-Datei verlinken, sondern die *.jasper-Datei, d.h. den kompilierten Report.

[[Datei:JasperReports-Handbuch_subreport1_wizard4.png]]

Danach sehen Sie einen Platzhalter für den Unterbericht im Entwurfsbereich. Beachten Sie bitte daß die Größe des Platzhalters unwichtig ist: die Ausdehnung des Unterberichts wird im Unterbericht definiert. Der Platzhalter ist lediglich wichtig, um die linke obere Ecke des Unterberichts festzulegen. 
Rechts neben dem Platzhalter sehen Sie die Eigenschaften des Unterberichts:

[[Datei:JasperReports-Handbuch_subreport2_params_none.png]]

Ein Unterbericht arbeitet meist mit Übergabe von Parametern, z.B. will man vom Hauptbericht den Inhalts des Feldes "Kostenstelle" an den Unterbericht übergeben. Dies müssen wir in den Eigenschaften des Unterberichts "deklarieren". In der Zeile "Parameters" steht nach Bedienung des Assistenten noch kein Wert. Für die Datenquelle XML gibt es außerdem einen Parameter XML_DATA_DOCUMENT, der immer übergeben werden muss: Die XML-Datenquelle des Hauptberichts. Hier eine Übersicht, welche Parameter übergeben werden:

[[Datei:JasperReports-Handbuch_subreport10_parameters.png]]

Die Zeilen mit Großschreibung sind die vorgegebenen Werte, der Parameter "Kst" speist sich aus dem JR-Feld "Kostenstelle". Das Beispiel zeigt, daß der Name für den Parameter beliebig ist.

'''Hinweis für Unterberichte mit Dezimalzahlen''': Wenn der Unterbericht mit Zahlen mit Nachkommastellen arbeitet, und Sie in JasperReports testen, dann müssen Sie noch die [[Berichtsdesign_mit_JasperReports#Datenquelle erzeugen|Parameter]] XML_LOCALE und XML_NUMBER_PATTERN wie folgt übergeben:

[[Datei:JasperReports-Handbuch_subreport2_params_number.png]]


=== Unterbericht mit Header und Footer vom Hauptbericht ===

Wenn der Unterbericht in einem normalen Gruppen- oder Detail-Band liegt, wird der Header und Footer vom Hauptbericht automatisch mitbenutzt. In vielen Fällen möchte man aber den Unterbericht nur ein mal ausgeben und legt ihn daher in das Summery-Band. Hier wird Standardmäßig der Header und Footer nicht ausgegeben oder wiederholt. Möchte man aber z.B. die Seitenzahl die im Footer liegt weiterhin angezeigt bekommen, gibt es eine Eigenschaft vom Hauptbericht, die man nur aktivieren braucht. Diese Eingenschaft nennt sich: Summary with Page Header and Footer.

Also einfach auf den Hauptbericht auswählen und in Eigenschaften diesen Punkt aktivieren.

[[Datei:JasperReports-Handbuch_subreport_header_footer.png]]


=== Konfiguration des Unterberichts ===

Nun können wir den Unterbericht öffnen, indem wir über dem Platzhalter die rechte Maustaste betätigen und "Open Subreport" wählen.

[[Datei:JasperReports-Handbuch_subreport3_open.png]]

Es erscheint ein neues Fenster mit einem leeren Entwurfsbereich. Sie könnten nun loslegen und im Detailbereich verschiedene Elemente gestaltet. Aber man muss bedenken daß ein Unterbericht für jeden Datensatz im Hauptbericht ausgeführt und eingebettet wird. Daher wird man vermutlich in den meisten Fällen im Unterbericht auf einen Filter zurückgreifen. Hier kommt dann wieder der oben genannte Parameter, z.B. "Kst" ins Spiel: Als ersten deklarieren wir den Parameter im Unterbericht, indem wir Links bei den Parametern die rechte Maustaste drücken, und "Hinzufügen..." wählen:

[[Datei:JasperReports-Handbuch_subreport4_param.png]]

Standardmäßig nennt IReport den Parameter "parameter1". Rechts können wir in den Eigenschaften des Parameters den Namen ändern, und "Use as a prompt" abwählen:

[[Datei:JasperReports-Handbuch_subreport4_param2.png]]

Weitere Änderungen sind nicht notwendig.

Wir ergänzen nun die "Report Query" [[Datei:JasperReports-Handbuch_report_query.png]] des Unterberichts von

<source lang="text">
/ergebnisse/ergebnis/ergebniselement/sqlerg/row
</source>

um einen Filter, der mit der Abfragesprache XPATH formuliert wird. Im obigen Beispiel würden wir jetzt nur die Zeilen der Datenquelle auswählen, wo die Nummer der Kostenstelle mit der des Hauptberichts übereinstimmt. Wir erinnern uns: letztere steht im Parameter "Kst". Anhand der vorhandenen Report Query können wir sehen, dass die Kostenstelle in den Spalten ("col") mit der id=5 steht. Der Ausdruck wird also um den Filter

<source lang="text">
[col[@id="5"]/wert='$P{Kst}']
</source>

ergänzt:

[[Datei:JasperReports-Handbuch_subreport4_query.png]]

Nun ändern wir im Entwurfsbereich des Unterberichts das Layout: für das aktuelle Beispiel wollen wir im Unterbericht eine Summe der Beträge für jede Kostenstelle ausgeben. Dazu müssen wir zunächst eine Gruppierung nach Kostenstelle hinzufügen:

[[Datei:JasperReports-Handbuch_subreport5_group1.png]]

Im Gruppierungsassistenten wählen wir das Feld "Kostenstelle" als Gruppierungsmerkmal, und im nächsten Schritt sagen wir, daß ein Gruppenkopf hinzugefügt werden soll:

[[Datei:JasperReports-Handbuch_subreport5_group2.png]]

Danach ist die Gruppierung als Band verfügbar:

[[Datei:JasperReports-Handbuch_subreport5_group3.png]]

In die Gruppierung ziehen wir dann das Feld "Summe":

[[Datei:JasperReports-Handbuch_subreport5_group4.png]]

Beim "Loslassen" des Feldes werden wir gefragt, ob wir eine Aggregatfunktion nutzen wollen; wir wählen hier die Summierung:

[[Datei:JasperReports-Handbuch_subreport5_group5.png]]

Danach ist das Feld verfügbar. Wir setzen noch das Label "Summe:" davor.

[[Datei:JasperReports-Handbuch_subreport5_group6.png]]

Den Detailbereich brauchen wir eigentlich nicht, wir können den ganz schmal machen. Danach speichern wir den Unterbericht, und gehen wieder zum Hauptbericht. Hier setzen wir den Unterbericht direkt unter das Feld "Kostenstelle":

[[Datei:JasperReports-Handbuch_subreport15_align.png]]

Danach können wir den Bericht mit der jew. Datenquelle ausführen. Das Ergebnis läßt je nach Datenmenge ein bisschen auf sich warten:

[[Datei:JasperReports-Handbuch_subreport20_erg.png]]


=== Einhängen des Berichts in Edustore ===

Damit der Bericht auch im Server nutzbar ist, muss noch folgendes eingestellt werden:

* Der Server sollte ausreichend RAM haben (Variable CATALINA_OPTS), weil hier XML als Datenquelle verarbeitet wird.
* Im Hauptbericht gibt es einen neuen Parameter SUBREPORT_DIR. Setzen Sie hier den Defaultwert ("Default value Expression" auf den Pfad, in dem die Dateien liegen (z.B. "/home/superx/webserver/tomcat/webapps/superx/WEB-INF/reports/").
* Kopieren Sie die .jasper Datei des Unterberichts in dieses Verzeichnis.
* Bei Nutzung von Versionskontrollsystemen haben Sie die *.jasper-Dateien vermutlich ignoriert (gitignore / svnignore). Sie müssen die Dateien daher mit "-f" adden / committen.

<blockquote>Vorsicht beim Einsatz von JasperSoft Studio: Die Anwendung erzeugt bei der Einzelbearbeitung eines Unterberichts nicht automatisch eine entsprechende .jasper-Datei beim Previewen des Hauptberichts (iReport machte das). Man muss also in Jaspersoft Studio im Bearbeitungsfenster oben immer "Compile Report" anklicken, um eine neue .jasper Datei zu erzeugen.
</blockquote>

== Kreuztabellen ==


=== Bedienung des Assistenten für Kreuztabellen ===

Für die Erstellung von Kreuztabellen gibt es einen eigenen Assistenten. Vorab sollte man aber zunächst ein "Summary"-Band erzeugen. Im folgenden Beispiel haben wir alle anderen Gruppierungen und Detail-Bands entfernt:

[[Datei:JasperReports-Handbuch_designer_crosstab1.png]]

Dann ziehen wir das Crosstab-Element in den Summary Band. Es erscheint der Assistent. Als Datenquelle nutzen wir die Abfrage des Berichts.

[[Datei:JasperReports-Handbuch_designer_crosstab2.png]]

Als nächsten definieren wir die Zeilendimension des Berichts:

[[Datei:JasperReports-Handbuch_designer_crosstab3.png]]

Wir wählen z.B. die Abschlüsse. Danach definieren wir die Spalten-Dimension:

[[Datei:JasperReports-Handbuch_designer_crosstab4.png]]

Wir wählen das Merkmal "Geschlecht". Danach definieren wir das Merkmal, das in den Zellen ausgegeben werden soll. Dies ist die Summe der Studierenden:

[[Datei:JasperReports-Handbuch_designer_crosstab5.png]]

Zum Schluß kann man ein Layout festlegen, und Zeilen- und Spaltensummen erzeugen:

[[Datei:JasperReports-Handbuch_designer_crosstab6.png]]

Im Entwurfsbereich erscheint ein neues Fenster mit der Kreuztabelle.

[[Datei:JasperReports-Handbuch_designer_crosstab7.png]]

Hier können wir nun Spaltenbreiten und Überschriften ändern:

[[Datei:JasperReports-Handbuch_designer_crosstab9.png]]

Das Ergebnis sieht wie folgt aus:

[[Datei:JasperReports-Handbuch_designer_crosstab8.png]]


=== Nachbearbeitung des Kreuztabellen-Assistenten ===

Der Assistent liefert nur einfache Kreuztabellen, ggf. wollen Sie diese im Nachhinein anpassen. Sie können z.B. mehr als zweistufige Hierarchien in Kreuztabellen einrichten, indem Sie im Report Inspector manuell neue Merkmale anlegen.

[[Datei:JasperReports-Handbuch_crosstab_new_row.png]]

Auch bei "Measures" können Sie neue "abhängige Variablen" anlegen, z.B. wenn Sie in einer Tabelle mit den Zeilen "Ausgaben" und "Einnahmen" die Ausgaben mit negativem Vorzeichen versehen wollen und dann saldieren wollen: Sie würden ein neues "Measure" anlegen, mit der Calculation="Sum", Typ "java.lang.Float", und der folgenden Expression bekommen alle Ausgaben ein negat. Vorzeichen:

<source lang="java">
($F{Kostenart}=="Ausgaben")?-$F{Betrag}:$F{Betrag}
</source>

Das neue Measure können Sie dann in die Zeilen- oder Spaltensummen ziehen.


=== Kreuztabellen im Gruppenfuß ===

Kreuztabellen lassen sich nicht nur im Summary Band nutzen, sondern auch in Gruppenfuß/Gruppenkopf-Bändern. Wenn Sie die Kreuztabelle z.B. in einen Groupfooter legen, müssen Sie den "Reset type“ der Gruppe anpassen. Das machen Sie indem Sie ein rechts klick auf die Kreuztabelle machen und dann auf "Crosstab data" klicken. Dort stellen Sie den "Reset type" auf "Group" und die "Reset group" auf die Gruppe in der die Kreuztabelle gelegt wurde. Wenn Sie das nicht machen funktioniert der Report nicht!


=== Kreuztabellen mit virtuellen Dimensionen ===

Sie können auch virtuelle Dimensionen in Kreuztabellen nutzen, indem Sie ähnlich wie bei der [[Berichtsdesign_mit_JasperReports#Gruppierung ohne eigenes Band|Gruppierung ohne eigenes Band]] mit Variablen arbeiten.

Um z.B. alle Studienfächer im Feld "1. Fach" auszugeben, und nur die Fächer Mathematik, Physik und Biologie zu einem Fach "Naturwissenschaften" zusammenzufassen, legen Sie eine neue Variable "fachgruppe" an, mit der Expression:

[[Datei:JasperReports-Handbuch_gruppierung_virtuell.png]]

In der Kreuztabelle können Sie nun z.B. in den Zeilen die Variable "fachgruppe" auswählen, und erhalten eine Tabelle mit der "künstlichen" Zeile "Naturwissenschaften":

[[Datei:JasperReports-Handbuch_gruppierung_virtuell2.png]]


=== Sortierung in Kreuztabellen ===

Zeilen- oder Spaltendimensionen werden in Kreuztabellen immer alphabetisch sortiert, egal wie die Sortierung in der Datenquelle ist. Das ist in der Regel kein Problem, aber wenn z.B. eine Zeilendimension anders sortiert werden soll, geht das nicht ohne weiteres. Hier ein Problembeispiel:

[[Datei:JasperReports-Handbuch_kreuztab_sortierung_falsch.png]]

Das Balkendiagramm übernimmt die Sortierung nach dem Schlüssel der Gehaltsgruppe aus der Datenquelle. In der Kreuztabelle wird die Zeilendimension "Bezeichnung der Gehaltsgruppe" angezeigt, und diese sortiert alphabetisch, was an dieser Stelle aber unsinnig ist: Der Eintrag "Kein Einkommen" sollte ganz oben stehen.

Wir schauen uns zunächst die Definition der Kreuztabelle an:

[[Datei:JasperReports-Handbuch_kreuztab_sortierung_richtig1.png]]

Die Zeilendimension sortiert aufsteigend nach Bezeichnungstext. Man kann auch keine alternative Expression als Sortierkriterium angeben. Wir müssen also einen Trick anwenden: wir nehmen den Sortierschlüssel mit in die "Bucket Expression" der Zeilendimension auf, und setzen ihn als Präfix davor:

[[Datei:JasperReports-Handbuch_kreuztab_sortierung_richtig2.png]]

Danach ist die Sortierung richtig:

[[Datei:JasperReports-Handbuch_kreuztab_sortierung_richtig3.png]]

Aber optisch ist das natürlich unschön, der Sortierschlüssel sollte am besten gar nicht angezeigt werden. Wir lösen das, indem wir den Anzeigetext wiederum so abwandeln, dass der erste Buchstabe nicht sichtbar ist. Java bietet dazu die Funktion "substring()":

[[Datei:JasperReports-Handbuch_kreuztab_sortierung_richtig4.png]]

Und siehe da: die Sortierung und Anzeige ist perfekt:

[[Datei:JasperReports-Handbuch_kreuztab_sortierung_richtig5.png]]

Dies ist nur ein Beispiel, wie man mit Hilfe von Java Expressions die Anzeige von Kreuztabellen variieren kann.


=== Parameter für Kreuztabellen ===

In Kreuztabellen hat man keinen direkten Zugriff auf die Variablen und Felder des Hauptberichts. Man kann die Werte aber als Parameter übergeben. Dazu gehen Sie wie folgt vor:

Sie machen den Parameter im Crosstab-Element bekannt, hier z.B. der Parameter "RSZ" für Regelstudienzeit):

[[Datei:JasperReports-Handbuch_crosstab_param1.png]]

Danach übergeben Sie den Parameter im Hauptbericht. Mit Rechtsklick auf das Cosstab Element können Sie eine Parameters-Map Expression hinterlegen, das ist einfach eine Zuweisung von einer oder mehreren Variablen zu jeweils einem Wert in der Groovy-Syntax mit "[Variable:Wert,...]". In dem Beispiel unten weisen wir dem Parameter "RSZ" den Wert des Feldes "RSZ" zu:

[[Datei:JasperReports-Handbuch_crosstab_param2.png]]

Danach können wir den Parameter in der Kreuztabelle nutzen, z.B. um in einer Spaltenüberschrift nur dann eine Zahl mit Soll-Kreditpunkten anzuzeigen, wenn die Fachsemester innerhalb der Regelstudienzeit liegen.

[[Datei:JasperReports-Handbuch_crosstab_param3.png]]

Und hier das Ergebnis für einen Studiengang mit 6 Semestern Regelstudienzeit:

[[Datei:JasperReports-Handbuch_crosstab_param5.png]]


=== Manuelle Kreuztabelle ===

Wenn die gewünschte Konfiguration/Einstellungen in der Kreuztabelle nicht möglich ist, kann eine Kreuztabelle mit Einschränkungen auch selber erstellt werden. Im Beispiel mit Semestern, muss vorher abgeschätzt werden wie viele Semester vorraussichtlich in den Spalten vorkommen werden. Für jedes Semester (z.B. für 10 Semester) wird dann eine Variable angelegt. Die erste bekommt das höchste Semester (wie im Screenshot zu sehen).

[[Datei:JasperReports-Handbuch_kreuztabelle_manuell_1.jpg]]

Das zweite Semester wir dann das höchste welches aber unterhalb von dem ersten liegen soll, usw.

[[Datei:JasperReports-Handbuch_kreuztabelle_manuell_2.jpg]]

Diese Semester können nun als Spalten verwendet werden mit der Option „blank when null“.


=== Layout von Kreuztabellen bearbeiten ===

Dieser Abschnitt befasst sich mit Themen zur Layoutanpassung.


==== Total einer ‚Row Group‘ entfernen ====

Wenn eine neue ‚Row Group‘ angelegt wird, wird automatisch ein dazugehöriges Total-Feld erzeugt und mit eingefügt:

[[Datei:JasperReports-Handbuch_Eingebettet_001.png|642x367px]]

Das ist in diesem Falle nicht erwünscht. Um dieses Feld zu entfernen, wird in den Properties der ‚Row Group‘ die ‚Total Position‘ = ‚none’ gesetzt:

[[Datei:JasperReports-Handbuch_Eingebettet_002.png|642x263px]]


==== Header von ‚Row Groups‘ für jede Zeile wiederholen ====

Im folgenden Screenshot ist eine Kreuztabelle dargestellt, bei welcher die Header der ‚Row Groups‘ nur einmal dargestellt werden:

[[Datei:JasperReports-Handbuch_Eingebettet_003.png|434x315px]]

Zwar ließe sich das Feld noch, so dass es bis zum nächsten ‚Row Header‘ reicht, aber in diesem Beispiel ist erwünscht, dass sich der Header für jede Zeile wiederholt:

[[Datei:JasperReports-Handbuch_Eingebettet_004.png|530x420px]]

Dazu wird die Funktion ‚Merge Header Cells‘ in den Properties der ‚Row Group‘ deaktiviert. Es kann sein, dass die Funktion einmal aktiviert und dann wieder deaktiviert werden muss, damit sie als deaktiviert erkannt wird.

[[Datei:JasperReports-Handbuch_Eingebettet_005.png|642x275px]]

Damit der Text in der ersten Spalte nicht abgeschnitten wird, wurde ‚Stretch with Overflow‘ in den Text-Field-Properties ausgewählt. Dadurch ist eine Lücke bei den anderen Spalten entstanden.

[[Datei:JasperReports-Handbuch_Eingebettet_006.png|509x404px]]

Um diese Lücke zu schließen wird der ‚Stretch Type‘ in allen folgend eingerahmten Textfeldern auf ‚Relative To Band Height (deprecated)‘ gesetzt:

[[Datei:JasperReports-Handbuch_Eingebettet_007.png|642x322px]]


==== ‚Static Field‘ und ‚Text Field‘ frei gestalten/bewegen ====

Im Default sind ‚Static Field‘ und ‚Text Field‘ in einer Kreuztabelle nicht frei positionierbar/gestaltbar. Um das zu ändern, wird im jeweiligen Bereich das Layout auf ‚Free Layout‘ eingestellt.

[[Datei:JasperReports-Handbuch_Eingebettet_008.png|642x279px]]


==== Reihenfolge der ‚Row Groups‘ ändern ====

Die Reihenfolge der ‚Row Groups‘ muss nachträglich im ‚Outline‘-Bereich geändert werden. Dies erfolgt per Drag and Drop im rot markierten Bereich:

[[Datei:JasperReports-Handbuch_Eingebettet_009.png|642x437px]]

Die Textfelder im Design-Bereich zu verschieben, reicht nicht aus, denn die ‚Row Group‘ selbst bleibt wo sie ist und dann würde nur das Textfeld in eine andere Row Group verschoben. Im folgenden Negativbeispiel wurden nachträglich im Design-Bereich die Textfelder Intervall und Datenherkunft vertauscht. Dadurch sind sie in der jeweils falschen ‚Row Group‘ gelandet:

[[Datei:JasperReports-Handbuch_Eingebettet_010.png|642x387px]]


== Diagramme ==

Um einen Bericht ansprechend zu gestalten dürfen Diagramme wie Torten- oder Balkendiagramme nicht fehlen. Diese in einen Bericht einzubringen ist auch nicht schwer.

<blockquote>Vorab sei aber darauf hingewiesen: Grafiken in JasperReports arbeiten nicht analog zu Kreuztabellen, in denen Daten nach Zeilen- oder Spaltenmerkmalen automatisch gruppiert und summiert werden. Für Grafiken sollten Sie gewährleisten, dass die Datenbasis für die Grafik '''bereits gruppiert und summiert''' sind, Sie können also keine Einzeldaten für Grafiken verwenden. Bei Datenblatt-Berichten in Edustore ist dies gewährleistet, wenn Sie im Feld "Felder" nur die Felder selektieren, nach denen in der Grafik gruppiert werden soll.
</blockquote>

=== Einfache Diagramme ===

Nehmen wir an wir haben eine Tabelle, die die Studierendenzahl mehrerer Semester nach Geschlecht aufführt. Hier ein Screenshot der Datengrundlage:

[[Datei:JasperReports-Handbuch_jaspersoft_design_query3.png]]

Die Tabelle enthält die Merkmale Geschlecht, Semester und Summe. Daraus erzeugen wir in Jaspersoft Studio (und weiter unten in iReport) ein Balkendiagramm.


==== Einfache Diagramme in JasperSoft Studio ====

Zunächst definieren wir die Sortierung der Daten. Im "Dataset and Query Dialog" sind die Felder der Datenquelle aufgeführt. Unten finden Sie den Reiter "Sorting":

[[Datei:JasperReports-Handbuch_jaspersoft_design_query2.png]]

Damit die Grafik richtig funktioniert müssen wir nach beiden Merkmalen (Semester und Geschlecht) sortieren. Das Semester sollte nicht alphabetisch nach Namen sortiert sein, sondern nach dem Zahlenschlüssel. Sonst ständen alle Wintersemester untereinander, und davor alle Sommersemester.

Dann ziehen wir aus der Palette das Chart Element in das Summary Band. Es startet automatisch ein "Chart Wizward". Hier wählen wir "Stacked Bar" als Grafiktypen:

[[Datei:JasperReports-Handbuch_jaspersoft_design_chart_wizard1.png]]

Nun müssen wir ihm sagen welches Feld die Y-Achse darstellt (hier "Summe"), und welches die X-Achse (hier "Semester der Belegung"). Das Merkmal zur Unterscheidung der Balkenfarben ("Series") ist das Geschlecht:

[[Datei:JasperReports-Handbuch_jaspersoft_design_chart_wizard2.png]]

Danach klicken wir auf "Finish", und die Grafik wird als Platzhalter im Summary Band eingefügt. Dort definieren wir noch die Breite der Grafik:

[[Datei:JasperReports-Handbuch_jaspersoft_design_chart1.png]]

Damit ist der Entwurf fertiggestellt. So sieht die Grafik aus:

[[Datei:JasperReports-Handbuch_jaspersoft_design_chart_wizard3.png]]

Es ist etwas ungünstig dass die Labels der X-Achse nicht ganz lesbar sind. Wir lösen dies mit Rotation der Labels um 45 Grad:

[[Datei:JasperReports-Handbuch_jaspersoft_design_chart_wizard4.png]]

So sieht es besser aus:

[[Datei:JasperReports-Handbuch_jaspersoft_design_chart_wizard5.png]]

Das Beispiel lädt zur weiteren Verfeinerung an.


==== Einfache Diagramme in iReport ====

Hier die Ansicht in iReports "Refresh Preview Data":

[[Datei:JasperReports-Handbuch_designer_chart2.png]]

Die Spalten der Tabelle sind selbsterklärend. Nun ziehen wir aus dem "Report Elements" die "Chart" in das Band "Summary".

[[Datei:JasperReports-Handbuch_grafik_chart_in_summary_ziehen.png]]

Dabei öffnet sich ein Fenster in dem Sie sich die Art der Grafik auswählen können. In diesem Beispiel wählen wir "Stacked Bar 3D".

[[Datei:JasperReports-Handbuch_grafik_chart_auswaehlen.png]]

Nach dem Klick auf "OK", geht es weiter mit den Inhalten der Grafik.

Als Dataset gibt es hier nur eine Auswahl.

[[Datei:JasperReports-Handbuch_grafik_dataset_auswaehlen.png]]

Daher akzeptieren wir dies mit einem Klick auf "Weiter".

Die "Series" sind die verschiedenen Unterteilungen eines Balkens. Die "Series" sind die verschiedenen Unterteilungen eines Balkens. Wir wählen hier das Merkmal "Geschlecht":

[[Datei:JasperReports-Handbuch_designer_chart3.png]].

Bei der X-Achse (in JasperReports heißt das "Category Axis") nehmen wie das Merkmal Semester, und bei der "Value expression" die Summe.

[[Datei:JasperReports-Handbuch_designer_chart4.png]]

Damit ist die Definition beendet. Wir können dann in den Eigenschaften der Grafik noch eine "Title Expression" festlegen, z.B. "Studierende nach Semester und Geschlecht". In der Vorschau sieht die Grafik so aus:

[[Datei:JasperReports-Handbuch_designer_chart5.png]]

Die Wintersemester werden noch nicht abgedruckt, dazu ändern wie die "Label rotation" auf 30°. Dies lässt die Schrift unter den Balken rotieren, damit längere Schriftzüge möglich sind.

[[Datei:JasperReports-Handbuch_designer_chart6.png]]

Wichtig für die Grafik war die Sortierung in der Datenquelle nach "dim_semester.quell_id". Mit "Series Colors" kann man die Farbe der Balken ändern etc.

<blockquote>Wenn sie jeden Balken bzw. Teil des Balkens zusätzlich mit den Werten ausgeben wollen, müssen sie in den Chart-Eigenschaften unter den "Bar*Properties" das Ankreuzfeld "Show labels" ankreuzen. Wenn es bereits angekreuzt ist, sollten Sie das Kreuz einmal entfernen und wieder setzen (Bug in iReport seit Version 4.x)
</blockquote>

=== Diagramme nach Tabelle ausgeben ===

Üblicherweise ähnelt ein Diagramm in JasperReports einer Kreuztabelle. Wenn nun ein Diagramm nach Vorgabe einer Tabelle ausgegeben werden soll, muss ein wenig getrickst werden.

Erläuterung:

In der Series expression werden die Zeilen angegeben.

In der Category expression werden die Spalten angegeben.

In der Value expression wird der Wert angegeben.

Um ein Diagramm nun zu erstellen muss pro Series + Category eine Categorie series angelegt werden und das entsprechende Feld angegeben werden.


=== Diagramme mit berechneten Werten ===

Wenn die einem Diagramm zugrunde liegende Tabelle noch Berechnungen erfordert, muss man mit Variablen arbeiten. Als Beispiel wird hier die Maske "Studierende und Studienanfänger (Zeitreihe)" benutzt. Das Ergebnis wird eine Tabelle mit Balkendiagramm der "Studierende und Studienanfänger im 1. Fachsemester (Zeitreihe)" sein.

Ein bereits fertiges Datenblatt könnte folgendermaßen aussehen:

[[Datei:JasperReports-Handbuch_grafik_datenblatt_ohne_grafik.jpg]]

Hier fehlt jetzt die Grafik, die in dem noch leeren Band "Summary" eingefügt werden soll. Wenn das Band noch nicht eingefügt wurde, einfach mit Rechtsklick auf Summary (im "Report Inspector") und dann auf "Add Band" um es anzuzeigen.

[[Datei:JasperReports-Handbuch_grafik_how_to_add_summary.png]]

Nun ziehen wir aus dem "Report Elements" die "Chart" in das Band "Summary".

[[Datei:JasperReports-Handbuch_grafik_chart_in_summary_ziehen.png]]

Dabei öffnet sich ein Fenster in dem Sie sich die Art der Grafik auswählen können. In diesem Beispiel wählen wir "Stacked Bar 3D".

[[Datei:JasperReports-Handbuch_grafik_chart_auswaehlen.png]]

Nach dem Klick auf "OK", geht es weiter mit den Inhalten der Grafik.

Als Dataset gibt es hier nur eine Auswahl.

[[Datei:JasperReports-Handbuch_grafik_dataset_auswaehlen.png]]

Daher akzeptieren wir dies mit einem Klick auf "Weiter".

Die "Series" sind die verschiedenen Unterteilungen eines Balkens. Da es in diesem Beispiel dafür keine Variable gibt, wird später noch per Hand eine Weitere hinzugefügt. Wenn es bei Ihnen möglich ist, klicken Sie rechts neben dem Feld auf den Button und fügen dort eine Variable ein. In diesem Beispiel wird als fester String "Frauen im 1. FS" eingegeben.

[[Datei:JasperReports-Handbuch_grafik_series_auswaehlen.png]]

Und dann wieder auf "Weiter".

Auf der X-Achse soll in diesem Beispiel die Semester erscheinen und auf der Y-Achse die Anzahl der Weiblichen Studierenden im 1. Fachsemester. Um dies zu erhalten wählt man als "category expression" die Variable "Semester" aus.

[[Datei:JasperReports-Handbuch_grafik_category_auswaehlen1.png]]

Dies geschieht, indem man auf den Button rechts neben dem Feld klickt,

[[Datei:JasperReports-Handbuch_grafik_category_auswaehlen2.png]]

dann doppelt auf das Feld "Semester" klickt und dann auf "Apply".

In den meisten Fällen werden hier Felder benutzt. Wenn Sie jedoch z.B. eine Variable benutzen wollen, müssen Sie nach dem Klick rechts auf den Button in dem neuen Fenster links unten z.B. auf "Variables" oder "Parameter" klicken. Dabei ändert sich der Inhalt von dem mittleren Feld.

[[Datei:JasperReports-Handbuch_grafik_category_auswaehlen3.png]]

Hier können Sie nun auch eine andere Auswahl treffen.

Das selbe gilt auch für "value expression". Der Unterschied ist hierbei, die "category expression" ist die Bezeichnung und in "value expression" dürfen nur Zahlen vorkommen, welche von JasperReports addiert werden können.

[[Datei:JasperReports-Handbuch_grafik_value_auswaehlen1.png]]

Hier wählen wir nun z.B. das Feld "1. FS Frauen" aus.

[[Datei:JasperReports-Handbuch_grafik_value_auswaehlen2.png]]

Nun noch abschließend auf Beenden drücken und wir erhalten das erste Ergebnis. Über "Preview" wird nun das Diagramm mit den Frauen aus dem 1. Fachsemester über die Semester angezeigt.

[[Datei:JasperReports-Handbuch_grafik_erstes_ergebnis.png]]

Um nun die männlichen Studenten aus dem 1. FS noch hinzuzufügen oder Änderungen an der gerade getroffenen Auswahl vorzunehmen klickt man mit der rechten Maustaste auf die Chart und dann auf "Chart Data". In dem Reiter "Details" kann man nun die eben angelegte Category bearbeiten/entfernen oder auch eine neue anlegen.

[[Datei:JasperReports-Handbuch_grafik_chart_details.png]]

Hier wollen wir jetzt noch die männlichen Studierende aus dem 1. FS noch Hinzufügen. Also klickt man auf "Hinzufügen.

[[Datei:JasperReports-Handbuch_grafik_chart_m_std_1fs_hinz.png]]

Die Eingabe funktioniert hier genau wie in dem Assistenten bei der Erstellung einer neuen Chart. Nur taucht jetzt das Problem auf, dass es kein Feld mit den Männlichen Studierenden gibt, sondern nur gesamt. Die Lösung ist aber ganz einfach. Zunächst geht man wieder in den "Expression editor" der "Value expression" und wählt das Feld "1. FS gesamt" aus, setzt dahinter ein Minuszeichen und danach wählt man noch das Feld "1. FS Frauen" aus. Jasper berechnet dann jeweils das Ergebnis und benutzt dieses als Value.

[[Datei:JasperReports-Handbuch_grafik_chart_m_std_1fs_hinz_1.png]]

Nun erhalten wir als Ergebnis folgende Tabelle:

[[Datei:JasperReports-Handbuch_grafik_zweites_ergebnis.png]]

Es gibt noch viele Änderungsmöglichkeiten unter Einstellungen wie z.B. "Label rotation" lässt die Schrift unter den Balken rotieren, damit längere Schriftzüge möglich sind und "Series Colors" um die Farbe der Balken zu ändern.

[[Datei:JasperReports-Handbuch_grafik_zweites_ergebnis1.png]]


=== Chart Customizer ===

Mit JasperSoft Studio können die über sog. "Chart Customizer" Details bzgl. des Layouts vor Diagrammen steuern. Im folgenden ein Beispiel:

Wir haben ein einfaches Balkendiagramm, in dem wir eine (automatisch) ermittelte Y-Achse mit Werten von 0-15 haben:

[[Datei:JasperReports-Handbuch_jr_chart_customizer_range1.png]]

Nun wollen wir den Bereich auf 12 (in 2er-Schritten ändern). Man könnte dies ganz leicht über die Eigenschaften ändern:

[[Datei:JasperReports-Handbuch_jr_chart_customizer_range2a.png]]

Hier kann man aber nicht die Schrittweite ändern. Wir legen dazu einen Chart Customizer vom Typ "Value Axis Range and Tick" an:

[[Datei:JasperReports-Handbuch_jr_chart_customizer_range2.png]]

und damit sieht das Diagramm so aus:

[[Datei:JasperReports-Handbuch_jr_chart_customizer_range3.png]]

Die Y-Achse zählt nun in 2er Schritten von 0 bis 12.

<blockquote>Noch ein Hinweis: Bei Y-Achsen mit kleinen Wertebereichen kann es vorkommen, dass JR die Y-Achse automatisch mit Intervallen mit Nachkommastellen versieht, also z.B. 1 - 1,5 - 2 - 2,5 etc. Bei manchen Maßen macht die Nachkommastelle keinen Sinn (z.B. wenn Studierende gezählt werden). Um das zu ändern gehen Sie in der Eigenschaften der Y-Achse (Chart → Value axis) und setzen bei der Eigenschaft "Value axis tick label mask" den Wert "#" (Pattern für ganzzahlig) ein. Damit wird nur noch ganzahlig hochgezählt.
</blockquote>

=== Balken Labels ===

In Balkendiagrammen können die exakten Zahlen nicht genau ermittelt werden. Aus diesem Grund wird oft gewünscht, die Zahlen noch mal schriftlich darzustellen.

[[Datei:JasperReports-Handbuch_balken_labels_1.png]]

Um die Zahlen anzeigen zu lassen muss einfach in den Chart Properties unter Advanced „Common Chart Properties → Plot → Show Labels“ auf true gesetzt werden.


== Booklets ==

Ab JR 6.2 oder höher (d.h. SuperX-Kernmodul 4.8 oder HISinOne-BI 2018.12) gibt es die Möglichkeit, Berichts-"Bücher" mit Deckblatt, Inhaltsverzeichnis und Schlußseite zu erstellen. Die Erstellung ist übersichtlicher als eine Kombination aus Haupt- und Unterbericht, und bietet beim Seitenlayout mehr Optionen, z.B. kann man in einem Booklet Hoch- und Querformat kombinieren.

Englische Anleitungen siehe

https://community.jaspersoft.com/documentation/tibco-jaspersoft-studio-user-guide/v60/report-books

Wg. der Version ist diese Möglichkeit in iReport nicht mehr verfügbar, Sie müssen JasperSoft Studio nutzen. Wenn Sie dort mit File -> New einen neuen Report erzeugen, können Sie bei Report type den Wert "Book report" wählen. Der Assistent fragt Sie dann, ob Sie Deckblatt, Inhaltsverzeichnis und die Schlußseite benötigen, kreuzen Sie die jew. Position an. Sie erhalten danach ein Entwurfsfenster mit dem Hauptbericht, der drei Abschnitte enthält: Das Deckblatt und Inhaltsverzeichnis ("Cover and table of contents"), den Buchinhalt ("Content") und die Schlußseite ("Backcover"):

[[Datei:JasperReports-Handbuch_booklet_main1.png]]

Wenn Sie die Datei speichern, werden die jew. Unter-Dateien automatisch mit angelegt, mit dem Zusatz "*_cover.jrxml", "*_toc.jrxml" und "*_backcover.jrxml".


=== Hauptbericht im Booklet ===


==== Aufbau des Hauptberichts ====

Startpunkt beim Booklet ist der Hauptbericht. Dieser hat keine "Bänder" im Sinne einer Ergebnisausgabe, insbesondere gibt es kein Detailband. Trotzdem arbeitet der Hauptbericht mit einer Datenquelle im Sinne eines Detailbandes, hier heißt das Band "Content". Für Makroberichte in SuperX-/BI müssen wir für alle Unterberichte dieselbe XML-Quelle verwenden, d.h. wir müssen im Hauptbericht genau eine Zeile der XML-Quelle filtern. Wir machen das mit XPATH mit dem Ausdruck 

<source lang="text">
/ergebnisse/ergebnis[@ordnr='0']/ergebniselement/sqlerg/row[@no='0']
</source>

Dies liefert die erste Zeile der ersten Tabelle des Makroberichts im Ergebnis.

Klicken Sie also oben auf die Datenquelle des Hauptberichts, und fügen Sie den Filter ein:

[[Datei:JasperReports-Handbuch_booklet_main2.png]]

Die Funktion „Read Fields“ funktioniert in diesem Fall nicht. Die Felder für den Hauptbericht werden manuell in den Sourcecode eingefügt. Dazu erstellen Sie zunächst, wie in [[Berichtsdesign_mit_JasperReports#Makroberichte als Datenquelle für JasperReports|Abschnitt 4.5]] beschrieben, ein JR-Template für den Makrobericht. Aus diesem Template kopieren Sie aus dem Sourcecode die Felder und fügen diese im Booklet ein. Fügen Sie alle Felder sowohl im Haupt- als auch in den Unterberichten des Booklets ein.

Im Content Band können Sie dann mit der rechten Maustaste die jew. Unterberichte verlinken. Die Technik ist identisch mit den normalen Haupt/-Unterberichten, nur dass das Seitenlayout nicht vom Hauptbericht zum Unterbericht vererbt wird.

Im Beispiel haben wir einen Unterbericht verlinkt:

[[Datei:JasperReports-Handbuch_booklet_main3.png]]

Im Feld "Component Expression" geben Sie den Unterbericht an. Im Feld "Tab name expression" können Sie den Namen des TABs in Excel definieren. Standardmäßig wird bei einem Booklet beim Export nach Excel also ein Arbeitsblatt mit mehreren Sheets.

Der Unterbericht wird mit den gleichen Parametern aufgerufen wie bei klassischen [[Berichtsdesign_mit_JasperReports#Konfiguration des Hauptberichts|Unterberichten]]. Der erste Unterbericht bekommt die ordnr 0, der zweite Unterbericht die ordnr 1 usw.:

[[Datei:JasperReports-Handbuch_booklet_main4.png]]


=== Übergabe von Layouts vom Hauptbericht an Unterberichte ===

Generell werden im Booklet keine Layoutvorgaben vom Hauptbericht an den jew. Unterbericht übergeben. Ausnahme: Die Property "net.sf.jasperreports.export.xls.detect.cell.type", die beim Excel Export als Zahl formatierte Zellen auch in Excel als Zahl ausgibt, wird im Hauptbericht gesetzt und dann an die Unterberichte übergeben.

Achtung: Je nach JasperSoft Studio Version kann man diese Property nicht in der graphischen Entwcklungsumgebung setzen, sondern nur im *.jrxml-Quellcode.


=== Booklet Deckblatt ===

Das Deckblatt ist ein normaler JasperReport mit Elementen im Titel-Band. Beachten Sie dass im Unterbericht auch Seitenränder und Seitenformate definiert sein müssen. Sie können auch vom Hauptbericht Parameter übergeben, hier z.B. das Semester:

[[Datei:JasperReports-Handbuch_booklet_cover1.png]]

Im Hauptbericht wiederum wird dieser Parameter dann übergeben, hier z.B. aus der Legende der Maske:

[[Datei:JasperReports-Handbuch_booklet_cover2.png]]


=== Booklet Inhaltsverzeichnis ===

Das Inhaltsverzeichnis ist ein Bericht ohne Datenquelle, und bekommt über die Evaluation Time="Report" die Anweisung, die Inhaltsdokumente nach Lesezeichen (HTML-Anchors) zu durchsuchen.

[[Datei:JasperReports-Handbuch_booklet_toc1a.png]]

Die Datenquelle ist leer, und über die Property

<source lang="text">
net.sf.jasperreports.bookmarks.data.source.parameter=REPORT_DATA_SOURCE
</source>

wird als Datenquelle der Content angegeben.

[[Datei:JasperReports-Handbuch_booklet_toc1b.png]]

Das Berichtsdesign ist vom Assistenten vorgegeben und relativ einfach. Sie können bis zu drei Ebenen für das Inhaltsverzeichnis angeben, jede Ebene benötigt ein eigenes Detailband.

[[Datei:JasperReports-Handbuch_booklet_toc2.png]]

Die Feldnamen im Bericht sollten nicht geändert werden. Sie können aber das Layout anpassen.


=== Booklet erster Detailbericht ===

Der Detailbericht ist ein normaler Unterbericht, d.h. er hat den Parameter "ordnr":

[[Datei:JasperReports-Handbuch_booklet_content1.png]]

Die Variable "ordnr" wird dann bei der Datenquelle des Unterberichts ausgewertet:

[[Datei:JasperReports-Handbuch_booklet_content2.png]]

Der Unterbericht soll sicherlich auch Seitenzahlen anzeigen, dazu fügen Sie noch ein "Page footer" Band hinzu, und erzeugen dort ein Textfeld mit dem Inhalt z.B.

<source lang="java">
"Seite "+$V{MASTER_CURRENT_PAGE}
</source>

Das Textfeld muss bei Evaluation time den Wert "Master" haben.

[[Datei:JasperReports-Handbuch_booklet_content3.png]]

Danach wird die Seitenzahl jedes Unterberichts an den Hauptbericht angepaßt.

Für das Inhaltsverzeichnis müssen Sie im jew. Detailbericht Lesezeichen (HTML-Anchors) und jeweils eine Ebene angeben. Wir können z.B. für das Textfeld der Überschrift einen Anker der Ebene 1 festlegen:

[[Datei:JasperReports-Handbuch_booklet_content4.png]]

Danach legen wir für das Gruppenband für das Textfeld mit dem Label der Gruppe (Fakultätsname) einen Anker der Ebene 2:

[[Datei:JasperReports-Handbuch_booklet_content6.png]]


=== Das fertige Booklet ===

So sieht das Booklet im Preview im JasperSoft Studio aus: Zuerst das Deckblatt...

[[Datei:JasperReports-Handbuch_booklet_preview1.png]]

... und dann auf Seite 2 das Inhaltsverzeichnis:

[[Datei:JasperReports-Handbuch_booklet_preview1b.png]]

und dann auf Seite 3 der erste Unterbericht:

[[Datei:JasperReports-Handbuch_booklet_preview2.png]]


== Schriften ==


=== Allgemeines zu Schriften ===

Für den Entwurf von Berichten ist es wichtig, daß die jew. Schriftart auch beim Server-System und beim Client verfügbar sind.

<blockquote>Ein häufiger Fallstrick ist hier: unter Windows wird mit JasperReports entworfen, und dort z.B. die Schriftart "Arial" gewählt. Der Report soll auf dem Server unter Linux laufen, dort gibt es die Schriftart nicht. Resultat: der Bericht ist nicht kompilierbar.
</blockquote>
Bei PDF-Dateien lassen sich Fonts ggf. auch in die Datei einbetten, bei Exportformaten wie OpenOffice oder Word ist dies nicht möglich. Sie sollten daher Schriftarten wählen, die auch beim Client mit größter Wahrscheinlichkeit installiert sind. Die sicherste Wahl ist es, Font-Familien anzugeben, z.B. "Serif".

Im Zweifelsfall installieren Sie die Schriftart auf allen beteiligten Systemen. TrueType Fonts lassen sich in JasperReports importieren und nutzen, sie können sogar in PDF-Dateien standardmäßig eingebettet werden. Im folgenden wird die Schriftart "Liberation Sans" installiert, die man auf [https://fedorahosted.org/liberation-fonts/ https://fe][https://fedorahosted.org/liberation-fonts/ dorahosted.org/liberation-fonts/] herunterladen kann. Entpacken Sie das Download Paket in einem beliebigen Verzeichnis.


=== Schriften in iReport einbinden ===

Achtung: wenn Sie iReport unter Windows nutzen, müssen Sie für die folgenden Schritte iReport als Admin starten:

Im Menü "Extras"->"Optionen" können Sie den Font importieren:

[[Datei:JasperReports-Handbuch_font_import_step1.png]]

Wählen Sie aus der Dateiliste zunächst den "Regular"-Font aus, z.B. die Sans-Serif-Variante. Im nächsten Schritt geben Sie dem Font einen Namen, und Sie wählen die zugehörigen Dateien für Fettdruck etc:

[[Datei:JasperReports-Handbuch_font_import_step2.png]]

Außerdem kreuzen Sie an, daß der Font in die jew. PDF-Datei eingebettet wird. Die nächsten zwei Dialoge (Locales, Font Mappings) lassen wir der Einfachheit halber erstmal weg. Wenn Sie dann OK drücken, ist der Font in iReport installiert. Sie können die Einstellungen jederzeit ändern, indem Sie auf "Edit Font" klicken:

[[Datei:JasperReports-Handbuch_font_import.png]]

Hier die Ansicht, wenn Sie auf "Edit Font" klicken:

[[Datei:JasperReports-Handbuch_font_import1.png]]

Am Ende des Formulars können Sie noch PDF-Exportoptionen wählen, z.B. ob die Schriftart in PDF-Dateien eingebunden werden soll. Achtung: beachten Sie lizenzrechtliche Fragen, die wenigsten Fonts sind ohne weiteres kopierbar. Wir empfehlen den Liberation-Font, der steht unter der OpenSource Lizenz GPL.


=== Schriften in '''JasperSoft Studio''' einbinden ===

Unter „Window“ → „Preferences“ können Sie Fonts einbinden:

[[Datei:JasperReports-Handbuch_font_import4.png]]

Nach einem Klick auf „Add“ öffnet sich ein neues Fenster. Dort geben Sie dem Font einen Namen und wählen die zugehörige Datei für den normale Ausführung des Fonts. Es gibt weitere Reiter für Bold, Italic und Bold Italic:

[[Datei:JasperReports-Handbuch_font_import5.png]]

Außerdem kreuzen Sie an, daß der Font in die jew. PDF-Datei eingebettet wird. Die nächsten zwei Dialoge (Locales, Font Mappings) lassen wir der Einfachheit halber erstmal weg. Wenn Sie dann OK drücken, ist der Font in iReport installiert.

Sie können die Einstellungen jederzeit ändern, indem Sie auf "Edit Font" klicken:

[[Datei:JasperReports-Handbuch_font_import6.png]]

Achtung: Beachten Sie lizenzrechtliche Fragen, die wenigsten Fonts sind ohne weiteres kopierbar. Wir empfehlen den Liberation-Font, der steht unter der OpenSource Lizenz GPL.


=== Default-Schriftart in iReport ===

Sie können die Default Schriftart in iReport einstellen:

[[Datei:JasperReports-Handbuch_ireport_default_font.png]]

Stellen Sie den Default-Font auf "Liberation Sans". Danach müssen Sie iReport neu starten.


=== Fonts auf dem Server ===

Um Schriftarten auf einen Tomcat-Server zu installieren, müssen die vier ttf-Dateien (normal, fett, kursiv, fett-kursiv) in den Ordner $JRE_HOME/lib/fonts kopiert werden. Für alle Java Anwendungen wie den Tomcat und JasperReports stehen dann die in dem verwendetem Java zur Verfügung.

Beispiel Arial unter Ubuntu 18.04:

Prüfen Sie mit dem Kommando

<source lang="bash">
ps fax | grep tomc
</source>

welcher Tomcat läuft. Sie bekommen eine Ausgabe z.B.

47769 ? Sl 36:25 /usr/lib/jvm/java-8-openjdk-amd64/bin/java -Djava.util.logging.config.file=/var/lib/tomcat8/conf/logging.properties -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Djdk.tls.ephemeralDHKeySize=2048 -Djava.protocol.handler.pkgs=org.apache.catalina.webresources -Xmx3500M -XX:MaxPermSize=400m -Djava.awt.headless=true -Dfile.encoding=UTF-8 -DSuperX-DB-PROPERTIES-SET=true -Djava.endorsed.dirs=/var/lib/tomcat8/endorsed -classpath /var/lib/tomcat8/bin/bootstrap.jar:/var/lib/tomcat8/bin/tomcat-juli.jar -Dcatalina.base=/var/lib/tomcat8 -Dcatalina.home=/var/lib/tomcat8 -Djava.io.tmpdir=/var/lib/tomcat8/temp org.apache.catalina.startup.Bootstrap start

Der erste Befehl zeigt den Pfad zu JRE_HOME, also /usr/lib/jvm/java-8-openjdk-amd64. Sie kopieren also die Dateien z.B.

arial.ttf

arialbd.ttf

arialbi.ttf

ariali.ttf

von

<source lang="text">
C:\Windows\winsxs\amd64_microsoft-windows-font-truetype-arial_31bf3856ad364e35_6.1.7601.17514_none_d0a9759ec3fa9e2d\*.ttf
</source>

nach

<source lang="text">
/usr/lib/jvm/java-8-openjdk-amd64/lib/fonts
</source>

und starten dann Tomcat neu.

<blockquote>Achtung: Sorgen Sie dafür dass Sie eine Lizenz für die jew. Fonts haben, weil diese bei PDF in die ausgelieferten Dateien eingebettet werden.
</blockquote>

=== Font Extension ===

Eine Alternative zu dem Einbinden der Schriftart über das Java Verzeichnise Font Extension. Diese hat aber nicht immer funktioniert. Um auf diesem Wege die Fonts auf einem Ziel-Server einzubinden, kann man die Schriftart als Font Extension exportieren, die dann wiederum in den CLASSPATH des Servers (bei Webanwendungen WEB-INF/lib) kopiert werden müssen:

[[Datei:JasperReports-Handbuch_font_import2.png]]

Nutzen Sie dazu den obigen Button "Export as extension", und wählen Sie einen Dateinamen mit der Endung ".jar".

<blockquote>Hinweis: Die Einbettung einer Font Extension in einer JasperReports-Laufzeitumgebung klappt erst mit JasperReports 3.7.2 oder höher.
</blockquote>
Wenn Sie in iReport auch PDF als Vorschau wählen, erzeugt iReport im Verzeichnis der jrxml-Datei auch eine entsprechende PDF-Datei. Damit diese die Fonts enthält, müssen Sie auch in iReport im CLASSPATH die Font-Extension einbinden. In diesem Falle ist es vorteilhaft, die Endung ".jar" (nicht ".zip") zu wählen, weil iReport hier nur jar-Dateien einbindet.

Noch ein Hinweis zu den Attributen "PDF Font name" und "PDF Encoding":

[[Datei:JasperReports-Handbuch_font_import3.png]]

Diese Attribute werden nicht mehr ausgewertet, wenn Sie mit Font Extensions arbeiten.


== TextField-Formatierung ==

In diesem Abschnitt werden verschiedene Einstellungen und Möglichkeiten der Formatierung in TextFields vorgestellt und erläutert.


=== Ausgabe von '''NULL''' als '''String''' verhindern ===

Falls NULL in einem TextField als String ausgeschrieben wird, kann dies verhindert werden, indem die Einstellung „Blank When NULL“ aktiviert wird. Das Feld bleibt dann leer:

[[Datei:JasperReports-Handbuch_text_field_formatting.png]]


=== Einzelne Wörter unterstreichen oder fett drucken ===

Wenn in einem TextField einzelne Wörter unterstrichen oder fett gedruckt werden sollen, einfach in den „Text properties“ unter „Markup“ „styled“ auswählen. In dem Textfield dann einfach um das zu unterstreichende Wort „ … “ schreiben oder „ … “ um es fett gedruckt auszugeben.

<blockquote>Bitte beachten, dass die PDF-Preview aus Jaspersoft Studio heraus keinen Fettdruck darstellt.
</blockquote>

=== Zahlen- und Datumsformat ===

Die Formatierung der Werte kann mit Hilfe des Attributes "Pattern" gesetzt

werden. Hier ein Beispiel:

[[Datei:JasperReports-Handbuch_textfield_pattern1.png]]

Das Textfeld bekommt das Pattern "0", d.h. es wird eine Ganzzahl inkl. 0 angezeigt. Der Platzhalter "#" steht für Zahlenbestandteile, hier wird eine 0 allerdings nicht angezeigt. Weitere Zahlen- und Datumsformate sind im Assistenten (linker Teil des Screenshots) sicher selbsterklärend.


=== Pattern Expression ===

Hat man pro Spalte / Zelle unterschiedliche Werte z.B. Datumsangaben und Währungseinheiten

oder Ganzzahlen und Kommazahlen und möchte diese unterschiedlich formatieren, so kann dies

mit dem Attribut "Pattern Expression" dargestellt werden.

Hier ein Beispiel für die Ausgabe von Ganzahlen und Kommazahlen:

<source lang="java">
$V{valueMeasure}.doubleValue() == Math.floor($V{valueMeasure}.doubleValue()) &&
!Double.isInfinite($V{valueMeasure}.doubleValue()) ?
"#0;#0" : "###0.00;###0,00"
</source>

Hier der Pattern Expression Editor:

[[Datei:JasperReports-Handbuch_ireport_pattern_expression_editor.png]]

Hier das Ergebnis:

[[Datei:JasperReports-Handbuch_ireport_pattern_expression_ergebnis.png]]


== Effiziente Formatierung ==

Wenn Sie keine Lust haben, jedes Textelement eines Berichts einzeln zu formatieren, empfehlen wir als ersten Schritt, Formatierungen zu kopieren.

Im Kontextmenü jedes Elements gibt es die Menüpunkte "Copy Format" und "Paste Format", die jeweils Formate kopieren und einfügen.

[[Datei:JasperReports-Handbuch_copy_format.png]]

Für Hochschulen ist ein einheitliches Layout der Berichte wichtig, und so bietet es sich an, zentrale Layouts zu definieren und dann wiederzuverwenden. In JasperReports heißen Layouts auch "Styles" bzw. Formatvorlagen. Ähnlich wie in OpenOffice Writer oder MS Word lassen sich Formatvorlagen definieren und zuweisen. Bei Änderungen der Formatvorlage werden diese Änderungen auf alle Elemente automatisch übertragen - auch nachträglich.

In der "Styles Library" werden z.B. einige häufig verwandte Layoutvorlagen angeboten.

[[Datei:JasperReports-Handbuch_styles_library.png]]

Sie können die Formate anwenden, indem Sie einfach die jew. Vorlage von der "Styles Library" per Drag and Drop auf das Ziel-Textfeld im Report Design ziehen und somit anwenden.

Sie können auch eigene Formatvorlagen zentral definieren. Im Menü Datei->New->Style geht es los: Wir erzeugen z.B. eine neue Style-Datei mit dem Namen "meinLayout.jrtx":

[[Datei:JasperReports-Handbuch_style_def_folie.png]]

In der jrtx-Datei definieren sie einen oder mehrere Formatvorlagen. Wir definieren z.B. die Formatvorlage "Textelemente", und geben ihr die Eingenschaft "SansSerif, Schriftgröße 12".

Danach können sie die Datei in der jrxml-Datei im Report Inspector unter "Styles" einbinden. Damit sind die Formatvorlagen in dieser Datei verfügbar, und können bei den Elementeigenschaften im Attribut "Style" zugewiesen werden:

[[Datei:JasperReports-Handbuch_styleref_design_folie.png]]

JasperReports nimmt standardmäßig den absoluten Pfad der jrtx-Datei, in der XML-Quelle sollten Sie diesen Pfad auf relativ umstellen.


== Conditional styles – '''Bedingte Formatierung''' ==

Wenn man in einzelne Textfelder "bedingte Formatierung" nutzen will (z.B. farbiger Hintergrund, Fettdruck), hat man früher mehrere Textfelder einzeln angelegt, mit dem gleichen Inhalt und einer jeweiligen "Print-when expression". Das geht seit JR 3.x eleganter mit den sog. "Conditional styles".

Hierfür wird ein Style angelegt und diesem diverse „Conditional Styles“ untergeordnet. Die „Conditional Styles“ enthalten Bedingungen und Formatierungseinstellungen. Der Style kann beispielweise einem Textfeld übergeben werden. Sobald die Bedingung eines „Conditional Styles“ erfüllt wird, werden die im „Conditional Style“ festgelegten Formatierungseinstellungen auf das Textfeld angewandt. Die Einstellungen im Textfeld selbst werden allerdings höher priorisiert. Eine detaillierte Erläuterung der Priorisierung anhand eines Beispiels findet sich in Abschnitt „Textfeld vs. Conditional Style – Priorisierung“


=== Beispiel in JasperSoft Studio – Schrift fett machen ===

Zunächst legen Sie die Formatierungen an, indem Sie unter Styles die rechte Maustaste drücken und über „Create Style“ einen Style erstellen, beispielsweise '''Daten_angepasst'''.

[[Datei:JasperReports-Handbuch_cond_style3.png]]

Durch Rechtsklick auf '''Daten_angepasst''' wird über „Create Conditional Style“ ein neuer Conditional Style hinzugefügt. Es erscheint ein neuer Unterknoten <No condition set>. Über die Properties können anschließend die zu erfüllende Bedingung als Expression, beispielsweise

<source lang="java">
$F{Name}.equals("Summe Aktiva")||$F{Name}.equals("Summe Passiva")
</source>

festgelegt und die Formatierungseinstellungen vorgenommen werden. In diesem Falle ist Fettschrift (bold) gewählt :

[[Datei:JasperReports-Handbuch_cond_style4.png]]

Um den Style inklusive seiner Conditional Styles auf beispielsweise ein Textfeld anzuwenden, werden die Properties des entsprechenden Feldes geöffnet. Im Reiter Appearance wird der gewünscht Style, in diesem Falle '''Daten_angepasst''',''' '''dem Textfeld zugeordnet:

[[Datei:JasperReports-Handbuch_cond_style5.png]]

Bei mehreren conditional styles wird die Reihenfolge ausgewertet, alle zutreffende conditional styles werden genommen. Die Reihenfolge wird direkt im XML oder per Drag&Drop geändert.

Es kam in der Vergangenheit bereits zu dem Phänomen, dass im Conditional Style Fettschrift gewählt war, aber nicht ins Textfeld übernommen wurde, während beispielsweise Kursivschrift problemlos und wie erwartet funktionierte. Eine genauere Beschreibung und Lösung findet sich im Abschnitt „Textfeld vs. Conditional Style – Priorisierung“


=== Beispiel in iReport – Schrift fett machen ===

Um z.B. einzelne Zeilen nach einer Bedingung fett zu machen oder nicht kann man so vorgehen: Zunächst legen Sie die Formatierungen an, indem Sie im Report Inspector unter Styles die rechte Maustaste drücken und ein Style hinzufügen, z.B. '''zw_maybe_bold''' für einen Style der Fett sein soll, wenn im Feld '''zw''' bestimmte Werte stehen.

[[Datei:JasperReports-Handbuch_styles.png]]

Danach erzeugen Sie mit Rechtsklick auf '''zw_maybe_bold''' eine neue Bedingung mit „Hinzufügen von Conditional Style“. Bei dem neuen Unterknoten <No condition set> klicken Sie auf die rechte Maustaste, dann Edit Condition. Hier können Sie wie gewohnt eine Bedingung in Form einer Expression eingeben, z.B.

<source lang="java">
$F{Zweckbestimmung}.equals("Gesamtausgaben")||$F{Zweckbestimmung}.equals("Gesamteinnahmen")
</source>

Dann müssen Sie den neuen Conditional Style anklicken

[[Datei:JasperReports-Handbuch_cond_style.png]]

und in den Eigenschaften bold auf true setzen.

Dann wählt man im Report designer die Felder aus, die ggfs. fett dargestellt werden sollen, und bei den Eigenschaften als Style '''zw_maybe_bold'''.

[[Datei:JasperReports-Handbuch_cond_style2.png]]

Wenn man mit Padding arbeiten will, kann man für den Style padding angeben, muss aber anscheinend manuell im jrxml leftpadding entfernen

<source lang="xml">
<box topPadding="0" leftPadding="0" bottomPadding="0">
</source>

Bei mehreren conditional styles wird die Reihenfolge ausgewertet, alle zutreffende conditional styles werden genommen. Es gibt zwar einen Menüpunkt „Reihenfolge ändern“ bei rechtem Mausklick, der ist jedoch deaktiviert, man kann die Reihenfolge aber direkt im XML ändern oder per Drag&Drop.

Leider kann man nicht einen conditionalstyle auf ein leere Zelle anwenden (z.B. Unterstrich), wenn man Excelexport macht, wird daraus einfach eine leere Zelle ohne Formatierung selbst wenn man Leerzeichen in der Text Expression hat.

Werden Variablen im conditional style verwendet, muss die evaluation time aktiviert werden über die property:

<source lang="xml">
<property name="net.sf.jasperreports.style.evaluation.time.enabled" value="true"/>
</source>

Siehe https://community.jaspersoft.com/blog/tip-data-set-variable-usage-conditional-style-table-component-jasper-reports

Ein Style kann auch mit einem anderen Style verknüpft werden, indem in dem entsprechenden Style unter dem Reiter „Style“ in dem Feld „Style“ das entsprechende Style ausgewählt wird. Somit können bestimmte Wiederholungen gespart werden.


=== Textfeld vs. Conditional Style – Priorisierung ===

In diesem Abschnitt wird anhand eines Beispiels aufgezeigt, dass Textfelder höher priorisiert sind als Conditional Styles und welche Fallstricke dadurch entstehen können. Das Beispiel:

Einem Textfeld wird ein Style zugeordnet, der einen Conditional Style enthält, welcher bei erfüllter Bedingung den Text fett und kursiv darstellen soll:

[[Datei:JasperReports-Handbuch_cond_style6.png]]

Im Textfeld selbst sind beide Einstellungen deaktiviert:

[[Datei:JasperReports-Handbuch_cond_style7.png]]

Das Ergebnis ist, dass im Bericht der Text dieses Feldes zwar kursiv, aber nicht fett dargestellt wird. Zum Testen werden weitere Formatierungseinstellungen im Conditional Style hinzugefügt, beispielsweise Unter- und Durchstreichen und auch dies wird umgesetzt. Die Bedingung des Conditional Styles ist also erfüllt.

Der Grund für dieses Verhalten ist nur mit Blick auf den Source-Code ersichtlich:

[[Datei:JasperReports-Handbuch_cond_style8.png]]

Dort findet sich in den Einstellungen des Textfeldes ''isBold=“false“''. Dieses Fragment ist dadurch entstanden, dass in der Designoberfläche von JasperSoft Studio für das Textfeld die Einstellung bold einmal aktiviert und dann wieder deaktiviert wurde. Im Source-Code wird nach dem ersten Aktivieren ''isBold=“true“'' hinzugefügt und beim Deaktiveren nicht wieder komplett entfernt, sondern auf false gesetzt. Da die Einstellungen im Textfeld selbst höher priorisiert werden, als jene der Conditional Styles, wird der Fettdruck des Conditional Styles nicht umgesetzt. Löscht man im Source-Code das Fragment ''isBold=“false“'', dann wird der im Conditional Style definierte Fettdruck umgesetzt.


=== Default Style ===

Es ist möglich einen Style als Default Style zu verwenden. Hierfür wird beim Style, nicht beim Conditional Style, die entsprechende Einstellung gesetzt:

[[Datei:JasperReports-Handbuch_cond_style9.png]]

Dieser Style wird nun auf jedes Feld angewandt, dem kein anderer Style zugeordnet ist.


== Expression Editor ==

Im Expression Editor werden die für die Ausgabe bestimmten Werte angegeben. Zahlen werden ohne Zusatz eingetragen. Feste String Werte werden zwischen Anführungszeichen gesetzt. Felder und Variablen können über ein Doppelklick auf den jeweiligen Namen unterhalb des Eingabefeldes eingefügt werden.

[[Datei:JasperReports-Handbuch_ireport_filter1.png]]

Zu den Feldern und Variablen gibt es auch noch Funktionen in dem 3. unterem Kästchen.

Ein Beispiel für Textausgabe:

Es soll ausgegeben werden „Auswertungszeitraum 1.1.<<Jahr>> bis 31.12.<<Jahr>>“.

Anstatt zwei statische Textfelder und zwei dynamische zu machen, legt man eine Expression an:

<source lang="java">
"Auswertungszeitraum: 1.1."+$F{legende_Jahr_value}+" bis 31.12."+$F{legende_Jahr_value}
</source>

<blockquote>Der Clou an JasperReports ist: da das Programm auf der Programmiersprache Java beruht, kann man in Expressions echten Java Code einfügen bzw. um eigenen Java Code erweitern. Wenn Sie z.B. wissen dass das benutzte Feld "$F{Lehr- und Forschungsbereich}" vom Typ String ist, können Sie alle in Java eingebauten String Funktionen benutzen, z. B. Substring, contains, indexOf, toLowerCase etc. Analog auch für andere Datentypen.
</blockquote>

=== Bedingungen ===

Bedingungen sind in dem Expression Editor auch möglich. Wenn z.B. eine Variable nur Ausgegeben werden soll, wenn der Wert größer, kleiner oder gleich einem anderem vorgegebenen Wert oder Variable sein soll, wird folgende Syntax verwendet:

<source lang="text">
<<Bedingung>> ? <<Ausgabe wenn Bedingung wahr>> : <<Ausgabe wenn Bedingung falsch>>
</source>

Bedingungen:

<source lang="java">
String1 == String2
String1 != String2
Nummer1 > Nummer2
String1.contains( String2 )
String1 == null
</source>

usw.

Wie oben angegeben: Wenn die Bedingung wahr ist, wird der Wert nach dem Fragezeichen genommen. Wenn die Bedingung falsch ist, wird der Wert nach dem Doppelpunkt genommen.


=== Umgang mit Zeichenketten ===

Häufig werden für Berichtsausgaben Zeichenketten manipuliert. Dadurch, daß JasperReports innerhalb der Java-Runtime läuft, stehen uns mächtige Methodenaufrufe zur Verfügung, die in Java schon eingebaut sind.

Für Zeichenketten hier eine Übersicht:

http://docs.oracle.com/javase/7/docs/api/java/lang/String.html


=== Umgang mit Datumsfeldern ===


==== Datumswerte aggregieren ====

Fürs Berichtsdesign auf aggregierter Ebene ist es oft praktisch, Datumswerte auf "grobere" Kategorien zu aggregieren, z.B. Monate, Quartale, oder Jahre. Um solche Werte auszugeben bzw. danach zu gruppieren können Sie eigene Variablen anlegen, die dann im Expression Editor mit Hilfe von Java berechnet werden. Hier ein Beispiel für eine Transformation vom Datum zur Einheit "Jahr-Monat":

<source lang="java">
(($F{Datum}.getYear()+1900)*100)+($F{Datum}.getMonth()+1)
</source>

Wenn wir annehmen, dass im Feld "Datum" ein Datums- oder Zeitstempel-Wert steht, dann wird über die o.g. Expression daraus ein Zahlenwert nach dem Muster Jahr (vierstellig) + Monat (zweistellig), z.B. für den 13.5.2013 würde daraus der Wert 201305. Nach diesem ganzzahligen Wert kann man dann sortieren und gruppieren.

<blockquote>Anmerkung: die o.g. Methoden getYear() und getMonth() sind seit einigen Jahren in Java "deprecated", d.h. sie könnten in zukünftigen Java Versionen entfallen. Aber da dies in den letzten 7 Jahren nicht passiert ist, können wir damit noch arbeiten und optimistisch sein. Falls die Methoden wirklich entfernt werden, muss man eigene statische Methoden mit dem in Java eingebauten Calender-Objekt erstellen, Codebeispiele dazu gibt es viele im WWW.
</blockquote>

wenn man Text "Erzeugungsdatum" und das Datum in einem Feld haben will geht so: 
"Erzeugungsdatum:"+new SimpleDateFormat("dd.MM.YYYY", Locale.GERMAN).format(new java.util.Date())


==== Zeichenketten zum Datumstyp konvertieren ====

Wenn Sie ein Datum als String-Feld geliefert bekommen, können Sie es mit Groovy zum Typen "java.util.Date" konvertieren, z.B. um danach zu sortieren. Wenn z.B. das Feld „Beginn“ den Typ String hat und gefüllt ist mit dem Wert "18.11.2020 18:05:00", dann können Sie eine Variable vom Typ java.util.Date erzeugen, mit der Expression:

<source lang="java">
Date.parse("dd.MM.yyyy hh:mm:ss", $F{Beginn})
</source>


=== Besonderheiten / Workarounds ===

* Bei Feldern mit Länge 1 klappte einfaches equals nicht, mit einer substring Anweisung geht es dann:

<source lang="java">
$F{legende_Art des Berichts_value}.substring(0,1).equals("B")
</source>

* Folgejahr berechnen: Selbst es das Feld Jahr gibt und es als Integer definiert ist in der Felderinfo, klappt der Bericht nur in JasperReports nicht in SuperX nicht wenn man schreibt: 
<source lang="java">
$F{legende_Jahr_value}.intValue()+1
</source>
geht nicht, statt dessen: 
<source lang="java">
new Integer($F{legende_Jahr_value}).intValue()+1
</source>
* Statt das Element table zu nutzen kann man auch manuell eine Tabelle erzeugen, in dem man per Rechtsklick auf ein Element Padding und Borders bearbeitet. Siehe http://www.youtube.com/watch?v=LbU6qTj3zQM
* Achten muss man dann darauf, dass Felder die Null sein können nicht „remove when blank“ haben und als TextFieldExpression besser nehmen: $F{Betrag}==null?" ":$F{Betrag}
* außerdem, wenn die erste Spalte einen stretch with overflow hat auch bei „stretch type“ „relative to tallest object“ einstellen
* Zeilenumbruch in Feld 
Markup auf html setzen und dann z.B.
<source lang="java">
"Plan "+$F{legende_Jahr_value}
</source>


=== Häufig benötigte Transformationen ===


==== Umrechnung Semester-tid in Namen ====

<source lang="java">
$V{Semester (Schlüssel)}.toString().endsWith("1")?("SS "+$V{Semester (Schlüssel)}.toString().substring(0,4)):("WS "+$V{Semester (Schlüssel)}.toString().substring(0,4)+"/"+(new Integer($V{Semester (Schlüssel)}.toString().substring(0,4))+1).toString())
</source>


==== Umrechnung Semester in akad. Jahr ====

Die folgende Formel formt die Semesterzahl aus dem Studierenden-Datenblatt in ein akad. Jahr um nach der Formel "Akad. Jahr=WS + darauf folgendes SS", z.B. WS 2009/2010 und SS 2010 werden zum akad. Jahr 2009:

<source lang="java">
$F{Semester der Belegung (Schlüssel)}.toString().endsWith("2") ? $F{Semester der Belegung (Schlüssel)}.toString().substring(0,4):(new Integer($F{Semester der Belegung (Schlüssel)}.toString().substring(0,4))-1).toString()
</source>

Die Formel nimmt beim WS die ersten vier Stellen des Semester-Schlüssels, und beim SS werden die ersten vier Stellen als Ganzzahl codiert, und dann wird 1 subtrahiert.

Da es diverse Definitionen von Akad. Jahr / Studienjahr / Prüfungsjahr gibt, kann man das obige Beispiel leicht für eigene Bedürfnisse abwandeln.


== Pattern Expression ==

Die Formatierung der Werte kann mit Hilfe des Attributes "Pattern" gesetzt

werden. Hat man allerdings unterschiedliche Werte z.B. Datumsangaben und Währungseinheiten

oder Ganzzahlen und Kommazahlen und möchte diese unterschiedlich formatieren, so kann dies

mit dem Attribut "Pattern Expression" dargestellt werden.

Hier ein Beispiel für die Ausgabe von Ganzahlen und Kommazahlen:

<source lang="java">
$V{valueMeasure}.doubleValue() == Math.floor($V{valueMeasure}.doubleValue()) &&
!Double.isInfinite($V{valueMeasure}.doubleValue()) ?
"#0;#0" : "###0.00;###0,00"
</source>

Hier der Pattern Expression Editor:

[[Datei:JasperReports-Handbuch_ireport_pattern_expression_editor.png]]

Hier das Ergebnis:

[[Datei:JasperReports-Handbuch_ireport_pattern_expression_ergebnis.png]]


== Fortgeschrittene Techniken bei Feldern ==

Textfelder enthalten standardmäßig nur den Feldnamen, aber die zugrunde liegenden [[Berichtsdesign_mit_JasperReports#Expression Editor|Ausdrücke]] lassen sich erweitern. Dabei kann auch alle Java Klassen zugegriffen werden, die sich im CLASSPATH befinden, z.B. [[Berichtsdesign_mit_JasperReports#Umgang mit Zeichenketten|java.lang.String]].

Hier ist ein Beispiel, in dem die Klasse "StringBuilder" (wird mit Java ausgeliefert , java.lang.StringBuilder) genutzt wird, um einen Text auszugeben:

[[Datei:JasperReports-Handbuch_expression_stringbuilder.png]]

Im Ergebnis sieht das so aus:

[[Datei:JasperReports-Handbuch_expression_stringbuilder1.png]]

Das Beispiel verdeutlicht: Man könnte da auch de.meineKlasse.erzeugeText("mein Text") schreiben, und diese Klasse dann in den CLASSPATH bei Jasper Start legen, und voila! Durch diese Funktionalität lassen sich also beliebige Java Klassen einbinden. Das gleiche geht übrigens auch mit Groovy.


== Einrücken von Feldern ==

Das Einrücken von Feldern macht man am besten, in dem man mehrere Textfelder definiert und jeweils eine printWhenExpression auf die Ebene einbaut.

Alternativer Versuch war folgendes:

Wobei Nachteil bei sehr langen Texten, bei denen strech with overflows zur Geltung kommt, dann die zweite Zeile nicht eingerückt wird.

Das Einrücken von Felder kann man für Textfelder (Strings) machen, indem der SuperX-Bericht eine Spalte einruecken definiert, der je nach gewünschter Einrückung eine Anzahl von x enthält, also z.B.

{| class="wikitable"
|-
!
!
!
|-
| Name
| Betrag
| Einrücken
|-
| 1. Überschrift
| 30000
| X (mindestens 1 x nötig)
|-
| 1.1 Unterüberschrift
| 15000
| Xxxxx
|-
| 1.3. UnterUnterübersichrift
| 3000
| xxxxxxxxx
|}

Dann kann man ein Textfeld erzeugen und bei TextFieldExpression einfach eintragen:

<source lang="java">
$F{Einruecken}.replace('x',' ')+$F{Name}
</source>

Für Zahlfelder (z.B. Double) geht das so nicht so gut, weil dann das Pattern der Darstellung ###0,00 nicht mehr greift.

Man definiert drei Felder nebeneinander, Beispiel:

{| class="wikitable"
|-
!
!
!
|-
| $F{Name}
| ${Betrag}

PrintWhenExpression

$F{Hierarchie_Ebene}.intValue()>=6

| ${Betrag}

PrintWhenExpression

$F{Hierarchie_Ebene}.intValue()<6

|}

Bei Ebene 1-5 wird ganz rechts ausgegeben, bei Ebene >=6 wird mittig ausgegeben.


== Berechnungen ==

Bei Berechnungen muss immer auch auf (ich nenne es mal) die Gültigkeit der Variable geachtet werden. Wenn eine Variable eine Summe bildet kann diese für z.B. „jetzt“ oder für eine Gruppe oder den ganzen Report gelten. Je nach Gültigkeit gilt z.B. die Summe nur für die aktuelle Gruppe (bei Gruppenbändern).

Achtung: Es gibt nicht nur eine Gültigkeit bei der Variable selber (Reset type) sondern auch bei dem Element in dem Bericht. Wenn eine Variable in den Bericht gezogen wird, besitzt das entstandene Element eigene Eigenschaften, bei dem dann die „Evulation Time“ eingestellt werden kann.


=== Prozentrechnung ===

Für die Prozentrechnung musst zuerst eine Variable z.B. mit dem Namen "Gesamt" anlegen mit den Eigenschaften:

<source lang="text">
Calculation = Sum
Reset type = Report
</source>

Dannach kann ein Textfeld mit dem Inhalt:

<source lang="java">
$F{Summe} / $V{Gesamt}
</source>

erstellt werden mit den Eigenschaften:

<source lang="text">
Expression Class = Double
Pattern = #.##0.00 % (kannst du unter Prozent auswählen)
Evaluation Time = Auto
</source>

In der Variable „Gesamt“ wird die Summe aus allen Werten des Feldes Summe gezogen.

Bei Prozentberechnungen in Grafiken muss in manchen Fällen der Wert auf 0 überprüft werden. Das kann man z.B. mit folgendem Code machen:

<source lang="java">
( $V{zahl1} == 0 || $V{zahl2} == 0 ? 0 : ( $V{zahl1} / $V{zahl1} * 100) )
</source>

Damit ist dann sichergestellt, dass es keine Probleme bei der Berechnung gibt, auch wenn die Zahlen mal leer sind.


=== Rundung ===

Wenn man runden möchte den Datentyp am besten auf BigDecimal stellen. Ansonsten wird schon mal aus 2,45 gerundet 2,4.


== Hyperlinks ==


=== Externe Links ===

Ein Textfeld kann auch als Hyperlink befüllt und ausgegeben werden. Vorab bemerkt: Hyperlinks funktionieren in internen Viewer von JasperSoft Studio sowie beim Export nach Excel nicht bzw. nur eingeschränkt, zumindestens wenn man POI als Excel Engine nutzt. Selbst wenn Hyperlinks ausgegeben werden, ist in den Sicherheitseinstellungen von Excel oder OpenOffice eine Änderung vorzunehmen, damit Hyperlinks auch aktiv sind. Da es hier komplexte Unterschiede bei MS Excel-/OpenOffice-Versionen gibt, haben wir das Thema nicht weiter verfolgt und raten davon ab.

In den anderen üblichen Ausgabeformaten (PDF, HTML) funktionieren die Hyperlinks.

Dabei gibt es zwei Varianten:

Das Textfeld hat als Markup Typ den Wert "html", und die Hyperlinks werden in HTML-Notation eingefügt. Beispiel:

[[Datei:JasperReports-Handbuch_hyperlink_pfd3.png]]

Hier der Quellcode der textField-Expression zum Kopieren:

<source lang="java">
$V{Gross_Forsch_Proj_Sprech}.replaceAll( "\n"," " )+"<a href=\"http://www.meinserver.de/url/\">Siehe Details</a>"
</source>

Im Ergebnis sieht das dann so aus:

[[Datei:JasperReports-Handbuch_hyperlink_pfd2.png]]

Bei Variante 2 erhält ein ReportElement im Quellcode die entsprechende Eigenschaft. In der von uns genutzten Version von JasperSoft Studio (6.5.1 final) war das noch nicht im GUI bearbeitbar, daher kann man das nur im Quelltext machen. Immerhin "zerstört" JasperSoft Studio dies beim Speichern nicht.

Die Eigenschaft des textField heißt hyperlinkType="Reference" und wird wie folgt belegt:

<source lang="xml">
<textField pattern="" isBlankWhenNull="true" hyperlinkType="Reference">
<reportElement mode="Opaque" x="363" y="22" width="259" height="22" forecolor="#000000" backcolor="#FFFFFF" uuid="48c8e2df-f231-4433-8836-309668e0a859">
<printWhenExpression><![CDATA[$V{Gross_Forsch_Proj_Sprech}.length() >100]]></printWhenExpression>
</reportElement>
<box>
<pen lineWidth="0.5"/>
<topPen lineWidth="0.5"/>
<leftPen lineWidth="0.5"/>
<bottomPen lineWidth="0.5"/>
<rightPen lineWidth="0.5"/>
</box>
<textElement textAlignment="Left" verticalAlignment="Middle" rotation="None" markup="html">

<paragraph lineSpacing="Single"/>
</textElement>
<textFieldExpression><![CDATA["Siehe Details"]]></textFieldExpression>
<hyperlinkReferenceExpression><![CDATA["http://meinserver/url"]]></hyperlinkReferenceExpression>
</textField>
</source>

Am Ende des textField wird dann im Element hyperlinkReferenceExpression das Ziel des Hyperlinks definiert. Da dies eine Expression ist, kann man die Hyperlinks auch dynamisch aufbauen. In der Ausgabe dies das dann so aus:

[[Datei:JasperReports-Handbuch_hyperlink_pdf.png]]

Je nach PDF Viewer muss man auch hier in den Sicherheitseinstellungen Hyperlinks aktivieren.


=== Interne Links/Anker ===

Auf einem Text Field kann ein Link eingetragen werden. Dafür muss man einfach mit der rechten Maustaste auf das Textfeld klicken und dann auf Hyperlink klicken.

Das erste Feld oben „Anchor Name Expression“ kann einen Text enthalten, auf den von einer anderen Stelle verwiesen werden kann. Es ist also eine Markierung.

Wenn ich einen Hyperlink Type wähle, kann ich auch Verweise in den generierten Bericht erzeugen. Z.B. kann ich hier den Type „LocalAnchor“ wählen.

Um z.B. ein Inhaltsverzeichnis zu erzeigen, welches im PDF bei klick auf ein Element dort hin springen soll, gehe ich zunächst zu der Stelle an der die Sprungmarke gesetzt werden soll und erzeuge dort ein Text Field mit der „Anchor Name Expression“ z.B. „Überschrift1“. Das Inhaltsverzeichnis muss dann auch aus Text Fields erzeugt werden und dort wähle ich dann bei Hyperlink type „LocalAnchor“. Nun habe ich unter der Auswahl von dem Hyperlink type ein neues Eingabefeld „Hyperlink Anchor Expression“. Dort trage ich jetzt exakt den gleichen Text „Überschrift1“ ein und im generierten PDF kann ich dort drauf klicken um an die Markierte Stelle zu kommen.


== Berichts-Properties setzen ==

Es gibt auf Berichtsebene die Möglichkeit, die Ausgabe der Berichte über sog. "Properties" zu steuern, teilweise auch formatspezifisch. So können Sie z.B. steuern, daß bei der Ausgabe nach Excel Zahlenfelder als Zahlenfelder ausgegeben werden, nicht als Textfelder.

Um die Berichts-Properties zu setzen, können Sie dies entweder für einzelne Berichte, order auch Server-weit einstellen.

Bei einzelnen Berichten gehen Sie im Report Inspector auf das oberste Element, und dort auf "Eigenschaften".

[[Datei:JasperReports-Handbuch_report_properties1.png]]

Sie erhalten dann eine Liste der Eigenschaften:

[[Datei:JasperReports-Handbuch_report_properties2.png]]

Dort können Sie Zeilen hinzufügen, bearbeiten und löschen. Eine Erläuterung der jew. Property erhalten Sie in dem jew. Dialog.

Um eine Property systemweit zu speichern, legen Sie eine Textdatei mit dem Namen "jasperreports.properties" an, und legen diese in den CLASSPATH. Im Kontext von Tomcat ist dies das Verzeichnis webapps/superx/WEB-INF/classes.


== Seitenlayout ==


=== Seitenumbrüche ===

Es gibt drei Typen von Seitenumbrüchen:

* Wenn der gesamte Bericht paginiert ist (Report-Eigenschaft "Ignore Pagination"="false"), berechnet JR aufgrund des Seitenformats die Seitenumbrüche automatisch, und fügt auch, sofern vorhanden, die Bänder "page header" und "page footer" hinzu.
* Bei eingeschalteten Eigenschaften des jew. Bandes "Start on a new page=true" werden Seitenumbrüche ebenfalls aufgeführt
* Es gibt für manuelle Seitenumbrüche in der Palette das Element "Break", das an beliebiger Stelle einen manuellen Seitenumbruch einfügt. Nun ist die Frage: wenn gesamte Bericht nicht paginiert ist ("Ignore Pagination"="true"), was dann bei einem Break passieren soll. In älteren JR Versionen (vor 4.8) wurde der Break trotzdem gesetzt. In Versionen ab 4.8 passiert das nicht mehr, man kann aber ab Version 5.1 über die Berichts-Property 
<source lang="text">
net.sf.jasperreports.page.break.no.pagination=apply
</source>
das alte Verhalten nachbilden.

In JasperSoft Studio oder iReport kann man zusätzlich noch beim Rendern des Berichts über den Parameter JRParameter.IS_IGNORE_PAGINATION steuern, ob Seitenumbrüche ausgeführt werden. Dies überlagert die Berichtseinstellung, wenn es angehakt ist. Das ist z.B. sinnvoll, wenn Sie im PDF Export Seitenumbrüche haben wollen, in Excel oder HTML aber nicht.

Leider kann man diesen Parameter nicht im Servlet setzen. Wenn Sie Seitenkopf/Fuß bei PDF wünschen, bei Excel aber nicht, nutzen Sie die Anleitung [[Berichtsdesign_mit_JasperReports#Seitenkopf und Seitenfuß bei Excel unterdrücken|unten]].

Es gibt verschiedene Möglichkeiten, wie sich das Detailband bei einem Seitenumbruch verhalten soll. Diese werden über den ‚Split Type‘ des Bandes gesteuert. Beispiel:

Bei einem Seitenumbruch wird die aktuelle Zeile des Detailbandes aufgeteilt und geht auf der nächsten Seite weiter. Der ‚Split Type‘ steht auf Stretch.

[[Datei:JasperReports-Handbuch_Eingebettet_011.png|642x170px]]

Falls erwünscht ist, dass jede Zeile ganz dargestellt wird, kann der ‚Split Type‘ auf Prevent gestellt werden:

[[Datei:JasperReports-Handbuch_Eingebettet_012.png|300x281px]]Das Ergebnis sieht wie folgt aus:

[[Datei:JasperReports-Handbuch_Eingebettet_013.png|642x223px]]


=== Die Höhe von Textfeldern dynamisch anpassen ===

[[Datei:JasperReports-Handbuch_layout1.png]]

Textfelder besitzen die Eigenschaft „Stretch With Overflow“. Wird diese aktiviert, passt das Textfeld dynamisch seine Größe, falls der Inhalt nicht in das Feld passt. Der Text bricht um und die Höhe des Feldes wird vergrößert. Damit auch alle anderen Felder derselben Zeile ihre Größe entsprechend anpassen wird der „Stretch Type“ aller Felder dieser Zeile auf „Relative To Tallest Object (deprecated)“ gesetzt. Die Felder passen ihre Höhe dann dem höchsten Feld dieser Zeile an. Im Detailband genügt dies. Für Bänder mit festgelegter Zeilenanzahl, wie beispielsweise dem Titelband ist eine weitere Einstellung vorzunehmen.

Um im Titelband die Funktion „Stretch With Overflow“ nutzen zu können, ist es notwendig allen Feldern in darunterliegenden Zeilen den „Position Type“ „Float“ zuzuweisen. Die Position der Felder verändedrt sich dann entsprechend der Höhe darüberliegender Felder.

[[Datei:JasperReports-Handbuch_layout2.png]]


=== Bericht ausgeben, ohne Dateninput ===

Wenn der Bericht bzw. das Layout mit Titelband etc. ausgegeben werden soll, obwohl es keine Daten gibt, dann wird die Funktion ‚When No Data Type‘ auf ‚All Sections No Detail‘ gestellt.

[[Datei:JasperReports-Handbuch_Eingebettet_014.png|336x374px]]


== Besonderheiten beim Export nach Excel ==

Für jedes Exportformat gibt es auf Berichtsebene bzw. darunter spezielle Properties, die Feinheiten des Zielformates festlegen. Dies wird im folgenden anhand des Excel-Exports von Formeln und Namen von Arbeitsblättern (Sheet-Names) gezeigt.

Bitte beachten Sie dass diese Hinweise für den "alten" Excel Export ("xls") gelten. Für die Exportformate xlsx, JExcel-API oder OpenOffice-Spreadsheets funktionieren diese teilweise nicht.

Um leere Zeilen im Excelexport zu vermeiden, im jrxml-Kopf:

<source lang="xml">
<property name="net.sf.jasperreports.export.xls.collapse.row.span" value="true"/>
<property name="net.sf.jasperreports.export.xls.remove.empty.space.between.columns" value="true"/>
<property name="net.sf.jasperreports.export.xls.remove.empty.space.between.rows" value="true"/>
</source>

wenn man Zahlenanpassung möchte

<source lang="xml">
<property name="net.sf.jasperreports.export.xls.auto.fit.row" value="true"/>
<property name="net.sf.jasperreports.export.xls.font.size.fix.enabled" value="true"/>
</source>

→ font wird ggfs. verkleinert

<source lang="xml">
<property name="net.sf.jasperreports.print.keep.full.text" value="true"/>
</source>


=== Excel-Formeln ===

Es gibt auch die Möglichkeit Zahlen nicht nur vorab zu berechnen, sondern beim Export nach Excel als Excel-Formel zu übergeben.

Um diese Funktion zu aktivieren muss im JRXML die Property mit folgender Zeile eingefügt werden:

<source lang="xml">
<property name="net.sf.jasperreports.export.xls.detect.cell.type" value="true"/>
</source>

Oder über die Report Properties:

[[Datei:JasperReports-Handbuch_excel_export_detect_cell_type1.png]]

Danach können in jedem Text Field in der Property expression:

[[Datei:JasperReports-Handbuch_excel_export_detect_cell_type2.png]]

folgende Einträge ergänzt werden:

[[Datei:JasperReports-Handbuch_excel_export_detect_cell_type3.png]]

Rechts neben net.sf.jasperreports.export.xls.formula wird die Formel für Excel eingetragen, allerdings ohne = am Anfang. Außerdem werden nicht alle Excel-Formeln unterstützt, insbesondere nicht deren deutsche Lokalisierung (z.B. oben SUMME(D119...). Details finden Sie in der [https://poi.apache.org/spreadsheet/formula.html POI]-Dokumentation. Um zu erfahren wie die Felder lauten, welche berechnet werden sollen, am besten den Bericht einmal ausführen und in Excel anzeigen lassen. Achtung: Wenn der Bericht noch bearbeitet wird, können sich die Felder noch verändern.

Bei net.sf.jasperreports.export.xls.pattern können speziell für Excel Formatangaben gemacht werden. In dem obigen Beispiel "#,##0.00;-#,##0.00" gibt es 2 Nachkommastellen und ein Tausender-Trennzeichen. Wenn z.B. Tausende von Euro angezeigt werden sollen, nimmt man als Pattern #.

<blockquote>Fallstrick: in der von uns getesteten Version (4.1.3) wurde die Property net.sf.jasperreports.export.xls.formula nur dann ausgewertet, wenn das das jew. Textfeld eine korrekte "Text field expression" hat, sie darf also nicht leer sein. Ob das ein Bug ist oder nicht ist uns derzeit unklar.
</blockquote>
Beispiel für eine komplexe Summenformel SUM(D7:D20,D28,D33,D40)

Man kann die Formel auch als Expression formulieren, z.b. um eine Division durch 0 zu verhindern. Setzen Sie dazu das Häkchen bei "Use an expression":

[[Datei:JasperReports-Handbuch_excelformula_expression.png]]

Das obige Beispiel führt die Formel "D91/D149" nur aus, wenn die Variable $V{Haush_Professoren_1} (die Quelle für die Zelle D149) einen Wert größer 0 hat. Wenn nicht, wird keine Formel reingeschrieben, sondern der Wert 0.

Diese Funktion bietet natürlich noch viel mehr Möglichkeiten, z.B. könnte man damit Excel-Zellennummern dynamisch berechnen etc. Beispiele dazu finden Sie in den JasperReport Demos in demo/samples/xlsformula/reports/XlsFormulaReport.jrxml.


==== Zeilennummern dynamisch berechnen (Ein Beispiel) ====

Will man dass in der gesamten Exceldatei immer Spalte F=D+E ist, braucht man nicht für jede Zeile feste Formeln eintragen.

Als Erstes schaut man in welcher Zeile die eigentlichen Daten anfangen, also z.B. nach den zwei Headerzeilen ganz am Anfang der Tabelle und den 3 Spaltenüberschriften, die pro Seite wiederholt werden.

Hier ein Beispiel

<source lang="java">
($F{Zweckbestimmung}.isEmpty()||($F{Soll}==null&&$F{Reste}==null))?"":"SUM(D"+(($V{PAGE_NUMBER}.intValue()*3)+$V{REPORT_COUNT}.intValue()+2)+",E"+(($V{PAGE_NUMBER}.intValue()*3)+$V{REPORT_COUNT}.intValue()+2)+")"
</source>

Elegant geht es auch so

<source lang="java">
($F{Zweckbestimmung}.isEmpty()||($F{Soll}==null&&$F{Reste}==null))?"":"INDIRECT(\"D\" & ROW())+INDIRECT(\"E\" & ROW())"
</source>

Das hat nur den Nachteil, dass die Formel in Excel nicht so schön ist.


==== WENN-/IF-Formel – '''Ein''' Fallstrick ====

Ein Fallstrick, der uns einige Stunden Arbeitzeit gekostet hat: die IF-Formel wird in OpenOffice und MS Excel mit dem Trennzeichen ";" für die THEN- und ELSE-Bedingung formuliert. JasperReports nutzt als Trennzeichen aber ",". Interessanterweise wird dann im fertigen Excel das "," als ";" angezeigt.


==== SUMIF – Summen mit Bedingungen (Bsp.: Zwischensummen ignorieren) ====

Wenn die Summe über einen großen Bereich gezogen werden soll, in dem auch Zwischensummen vorkommen, gibt es die Folgende Formel:

<source lang="java">
SUMIF(A"+$V{zeile_start}.intValue()+":A"+$V{zeile_ende}.intValue()+",\"<>Summe*\",B"+$V{zeile_start}.intValue()+":B"+$V{zeile_ende}.intValue()+")
</source>

Wenn die Zwischensummen mit addiert werden würden, wäre das Ergebnis doppelt so hoch wie es sein sollte. Die Funktion SUMIF beinhaltet 3 Bereiche. Zuerst wird der Bereich eingegeben, auf den die Bedingung angewendet wird:

<source lang="java">
A"+$V{zeile_start}.intValue()+":A"+$V{zeile_ende}.intValue()+"
</source>

Hier ist das z.B. von A1 bis A10.

Danach kommt die Bedingung:

\"<>Summe*\"

Das bedeutet, es werden alle Zeilen genommen, die '''''NICHT''''' mit „Summe“ anfangen.

Als letztes kommt der Bereich, der summiert werden soll:

<source lang="java">
B"+$V{zeile_start}.intValue()+":B"+$V{zeile_ende}.intValue()+"
</source>

Hier ist das z.B. von B1 bis B10.

In diesem Beispiel werden alle Zahlen zwischen B1 und B10 aufsummiert, wenn in der entsprechenden Zeile in der Spalte A der Text nicht mit „Summe“ beginnt.


==== Statt 0-Werten eine leere Zelle ausgeben ====

Im Standardfall wird eine 0 ausgegeben, falls eine Formel in Excel auf leere Zellen oder Zellen mit einer 0 verweist. Um stattdessen eine leere Zelle auszugeben wird die Property Property net.sf.jasperreports.export.xls.pattern genutzt. Das obige Beispiel wird erweitert:

<source lang="text">
###0.00;-###0.00;;@
</source>

Die jeweiligen Zellen weisen nun 2 Nachkommastellen aus und zudem werden 0-Werte nicht mehr angezeigt.


==== OpenOffice vs Excel ====

OpenOffice kommt mit folgender Berechnung klar

<source lang="text">
"INDIRECT(\"E\" & ROW())+INDIRECT(\"F\" & ROW())-INDIRECT(\"G\" & ROW())-INDIRECT(\"H\" & ROW())":""
</source>

Excel macht hier Ärger, wenn eine der Zellen Null ist, wird als Gesamtergebnis #WERT angezeigt, entweder Sum-Formel benutzen, oder noch mal mit IF prüfen, ob Zelle gefüllt ist

Struktur ist (IF(Zelle leer,0,sonst Zellenwert))

<source lang="text">
"IF(INDIRECT(\"E\" & ROW())=\"\",0,INDIRECT(\"E\" & ROW()))+IF(INDIRECT(\"F\" & ROW())=\"\",0,INDIRECT(\"F\" & ROW()))-IF(INDIRECT(\"G\" & ROW())=\"\",0,INDIRECT(\"G\" & ROW()))-IF(INDIRECT(\"H\" & ROW())=\"\",0,INDIRECT(\"H\" & ROW()))":""
</source>


=== ‚Stretch with Overflow‘ in Excel korrekt verarbeiten ===

Wenn Sie eine Zelle haben mit besonders langem Text, z.B. „Unterstützungen auf Grund der Unterstützungsgrundsätze, Fürsorgemaßnahmen sowie Kosten nach dem Arbeitssicherheitsgesetz“, hilft es, nur bei der Zelle, Line Spacing auf double zu setzen, dann sieht es in Excel besser aus.

Es wird das Stretch richtig verarbeitet.

<source lang="xml">
<property name="net.sf.jasperreports.export.xls.auto.fit.row" value="true"/>
<property name="net.sf.jasperreports.export.xls.font.size.fix.enabled" value="true"/>
</source>

→ verkleinert fonts bei bedarf

<source lang="xml">
<property name="net.sf.jasperreports.print.keep.full.text" value="true"/>
</source>


=== Pagination in Excel-Dokumenten ===

In Excel-Dokumenten in die Seitengröße naturgemäß irrelevant. Trotzdem wird das im jrxml gesetzte Seitenformat beim Excel-Export beachtet. Das stellt sich so dar, dass im Excel-Dokument der „Rest der Seite“ durch einzelne breitere beziehungsweise höhere Zellen gefüllt wird. Das sieht beispielsweise folgendermaßen aus:

[[Datei:JasperReports-Handbuch_excel_export_pagination1.png]]

Unter dem Tabellenschluss ist die Zeile 84 so hoch, dass die im jrxml eingestellte Seitenhöhe erreicht ist. Um das zu verhindern wird für den gesamten Bericht isIgnorePagination=“true“ gesetzt. Die Einstellung wird im source-Code ganz oben im Tag <jasperReport isIgnorePagination=“true“> gesetzt oder über die grafische Oberfläche:

[[Datei:JasperReports-Handbuch_excel_export_pagination2.png]]


=== Excel-Export in einzelne Tabellenblätter ===

Normalerweise werden beim Export nach Excel die Berichtsinhalte in das erste Tabellenblatt geschrieben. Je nachdem wie Sie auf Berichtsebene die Property net.sf.jasperreports.export.xls.one.page.per.sheet setzen, wird der Seitenumbruch gesteuert. Setzen Sie den Wert auf "true", dann führt jeder Seitenumbruch zu einem neuen Sheet bzw. Arbeitsblatt in der Excel-Datei. Standardmäßig werden diese dann "Page 1", Page 2" etc. benannt.

Wenn Sie die Namen der Sheets explizit vergeben wollen, können Sie dies wie folgt machen: Wenn Sie z.B. die Berichtsproperty net.sf.jasperreports.export.xls.sheet.names.all auf den Wert

"Hauptseite/wichtige Seite/Unwichtige Seite" setzen, bekommen Sie drei Sheets mit den jew. Namen, d.h. der "/" fungiert als Trennzeichen. Dementsprechend sollte im Namen des Sheets kein "/" auftauchen.

Seit JR 4.1 gibt es auch die Möglichkeit, die Sheetnamen dynamisch zu vergeben. Auch hier werden Properties mit Expressions genutzt.

Es gibt verschiedene Möglichkeiten Berichtsinhalte in verschiedene Excel-Tabellenblätter zu verteilen. Im Folgenden werden zunächst Möglichkeiten betrachtet, welche bei Einzelberichten in Frage kommen. Danach geht es um die klassische Haupt- und Unterberichtsstruktur und zuletzt um Booklets, welche die in den meisten Fällen wohl elegantere Alternative zu klassichen Haupt- und Unterberichten darstellen.


==== Einzelne Berichte ====

Nehmen wir an wir haben einen Bericht mit der Gruppierung auf die Spalte "LFB", im Gruppenkopf befindet sich ein Text Field mit der Expression $F{LFB}.

Sie können diesem Textfeld eine Property net.sf.jasperreports.export.xls.sheet.name geben:

[[Datei:JasperReports-Handbuch_excel_export_sheets_names.png]]

Das Textfeld erhält somit beim Füllen des Berichts den jew. Wert, z.B. "Anglistik, Amerikanistik", und diese Überschrift steht auch im Gruppenkopf. Wenn der Gruppenkopf das Attribut "Start on a new page" hat, dann beginnt der Gruppenkopf auf einer neuen Seite und, dank der Berichts-Property net.sf.jasperreports.export.xls.one.page.per.sheet , erzeugt Excel / OpenOffice dann ein neues Sheet mit dem Namen Anglistik, Amerikanistik. Beim Sheetnamen soll nur sichergestellt werden, dass kein "/" im Text vorkommt, daher der replace-Befehl zur Sicherheit. Hier ein Screenshot in OpenOffice:

[[Datei:JasperReports-Handbuch_excel_export_sheets_names2.png]]

Man kann das gesamte Verhalten auch deaktivieren, indem man auf Berichtsebene das Attribut "Ignore Pagination" auf "true" setzen. In diesem Falle werden alle Seitenumbrüche ignoriert.

<blockquote>Hinweis für SuperX/Edustore Nutzer: leider haben wir in älteren Kernmodul-Versionen dieses Attribut " Ignore Pagination" im Servlet fest auf "true" gesetzt, so dass Sie diese Funktion im Servlet erst ab Version SuperX 4.5 bzw. HISinOne-BI 7.0 nutzen können.
</blockquote>

==== Haupt- und Unterberichte ====

Das vorherige Kapitel hat aufgezeigt, wie innerhalb eines einzelnen Einzelberichtes mit gezieltem setzen von Seitenumbrüchen ein solcher Berichte auf verschiedene Tabellenblätter eines Excel-Dokumentes augeteilt wird.

Um mehrere Einzelberichte in einem Excel-Dokument gesondert auf verschiedene Tabellenblätter aufzuteilen eignen sich klassiche Haupt- und Unterberichtsstrukturen (vgl. Kapitel 3.5). Die simpelste Methode wäre das Seitenlayout eines Berichtes so groß zu wählen, dass der gesamte Bericht auf eine Seite passt.

Falls Haupt- und Unterberichte verwendet werden, darauf achten, dass der Hauptbericht direkt unter dem letzten Unterberichtselement endet. Ansonsten entsteht ein weiteres leeres Tabellenblatt. Der folgende Screenshot zeigt, wie es nicht sein sollte. Hier muss das Summary-Band verkleinert werden, sodass es mit dem Unterberichtselement endet.

[[Datei:JasperReports-Handbuch_excel_export_main-_subreport.png]]


==== '''Individuelle Gestaltung''' bei Booklets ====

Booklets bieten diverse Vorteile beim Gestalten der einzelnen Seiten beziehungsweise Sheets. Denn jeder Unterbericht kann hier individuell formatiert werden. Dies betrifft beispielsweise die Definition von Sheetnamen, da hierfür die Eigenschaft "Tab name expression" im "Buch"-[[Berichtsdesign_mit_JasperReports#Hauptbericht im Booklet|Bericht]] vorgesehen ist. Auch das Problem, dass ein Sheet in diesem Falle nicht mehrere Seite umfassen darf (und man somit die Seitengröße unrealistisch groß machen muss) ist damit behoben.

Eine Ausnahme stellen jedoch die Properties dar. Diese werden im Hauptbericht gesetzt und gelten für alle Unterberichte.


=== Das Drucklayout in Excel konfigurieren ===


==== '''Seitenränder und Kopfzeile im Drucklayout formatieren''' ====

Zum Anlegen eines Textes in der Kopfzeile gibt es die Properties

<source lang="xml">
<property name="net.sf.jasperreports.export.xls.sheet.header.center">
<property name="net.sf.jasperreports.export.xls.sheet.header.right">
<property name="net.sf.jasperreports.export.xls.sheet.header.left">
</source>

Je nach gewünschter Position wird der jeweiligen Property ein Wert übergeben. Ein Beispiel:

<source lang="xml">
<property name="net.sf.jasperreports.export.xls.sheet.header.center">
<![CDATA[&"Liberation Sans,Bold"&10Meldung der Ist-Besetzung]]>
</property>
<property name="net.sf.jasperreports.export.xls.sheet.header.right">
<![CDATA[&"Liberation Sans,Bold"&10Anlage 1 &"Liberation Sans,Regular"&10 (zu VwV HWiF 3.2.1)]]>
</property>
</source>

In diesem Beispiel wird zentral der Text „'''Meldung der Ist-Besetzung'''“ übergeben. Der Text ist in der Schriftart Liberation Sans und fettgedruckt formatiert (&"Liberation Sans,Bold"), sowie in Schriftgröße 10 (&10).

Rechts wird der Text „'''Anlage 1 '''(zu VwV HwiF 3.2.1)“ verwandt. Der erste Teile „'''Anlage 1'''“ ist wie der zentrale Text formatiert (&"Liberation Sans,Bold"&10). Für den zweiten Teil „(zu VwV HwiF 3.2.1)“ wird von Fett- auf Regulärdruck gewechselt (&"Liberation Sans,Regular"&10). Weitere Möglichkeiten zur Formatierung finden sich auf https://poi.apache.org/apidocs/dev/org/apache/poi/xssf/usermodel/extensions/XSSFHeaderFooter.html.

Damit die Kopfzeile im Drucklayout sichtbar ist, ist es notwendig den Seitenrand groß genug zu gestalten. Dafür werden folgende Properties genutzt:

<source lang="xml">
<property name="net.sf.jasperreports.export.xls.print.page.left.margin" value="20"/>
<property name="net.sf.jasperreports.export.xls.print.page.right.margin" value="20"/>
<property name="net.sf.jasperreports.export.xls.print.page.top.margin" value="40"/>
<property name="net.sf.jasperreports.export.xls.print.page.bottom.margin" value="10"/>
</source>


==== Vordefinierte Zeilen im Drucklayout auf jeder Seite wiederholen ====

Um im Drucklayout beispielsweise einen Tabellenkopf auf jeder Seite zu wiederholen, wird die Property

<source lang="xml">
<property name="net.sf.jasperreports.export.xls.sx_repeating.rows.range" value="3:7"/>
</source>

genutzt (dafür eigene Klasse de.superx.servlet.SxJRXlsExporter geschaffen und de.superx.servlet.JasperCreator angepasst – aktuell in NHS-Pack für 7.1 enthalten). Der Wert gibt an, welche Zeilen des Excel-Dokumentes im Drucklayout auf jeder Seite wiederholt werden. Im Beispiel (''value="3:7"'') sind die Zeilen 3 bis 7 betroffen.


==== Seitenumbrüche im Drucklayout verhindern ====

Teilweise ist es wünschenswert Seitenumbrüche im Drucklayout zu verhindern, sowohl in der Breite als auch in der Höhe. Hierfür werden die Properties

<source lang="xml">
<property name="net.sf.jasperreports.export.xls.fit.width" value="1"/>
<property name="net.sf.jasperreports.export.xls.fit.height" value="1"/>
</source>

genutzt. Also value kommen hier 1 und 0 für entweder true oder false infrage. Setzt man der Wert true, dann wird nicht umgebrochen. Das bedeutet für dieses Beispiel, dass der gesamte Inhalt des Excel-Dokuments auf eine Seite gedruckt würde.


=== Zellen verbinden ===

<source lang="xml">
<property name="net.sf.jasperreports.export.xls.export.xls.sx_cell_merge" value="0,6,0,7|1,2,3,4"/>
</source>

1,1,4,1 - will merge from B2 to E2. Remember it is zero based indexing.


=== Zellschutz aktivieren ===

<source lang="xml">
<property name="net.sf.jasperreports.export.xls.password" value="gmmmyflb"/>
</source>

→ Alle Zellen sind mit Passwort geschützt.

Wenn bestimmte Spalten/Zeilen nicht geschützt sein sollen:

Property net.sf.jasperreports.export.xls.cell.locked false.

Dies kann man auch über eine komplexe PropertyExpression steuern, z.B.

(

<source lang="java">
($F{Zeile}!=null&&(
$F{Zeile}.indexOf("A")>-1||
$F{Zeile}.indexOf("B")>-1||
$F{Zeile}.indexOf("C")>-1||
$F{Zeile}.equals("I.")||
$F{Zeile}.equals("II.")||
$F{Zeile}.equals("III.")||
$F{Zeile}.equals("IV.")||
$F{Zeile}.equals("V.")||
$F{Zeile}.equals("VI.")||
$F{Zeile}.equals("VII.")||
$F{Zeile}.equals("VIII.")))||
($F{Kontengruppe}!=null&&$F{Kontengruppe}.equals("53,54,58"))||
($F{Name}!=null&&(
$F{Name}.startsWith("= Summe der (ordentlichen")||
$F{Name}.startsWith("Ordentliche ")||
$F{Name}.startsWith("- ordentliche")||
$F{Name}.startsWith("+/- Finanz")||
$F{Name}.startsWith("Summe Investitionen")||
$F{Name}.startsWith("Summe Finanzbedarf")||
$F{Name}.startsWith("Summe Deckung")||
$F{Name}.startsWith("5.1 E")||
$F{Name}.startsWith("Summe sonstige betriebl")||
$F{Name}.startsWith("Sonstige betriebliche")||
$F{Name}.startsWith("5.1.) Erträge aus Zuweisungen")||
$F{Name}.startsWith("Materialaufwand")||
$F{Name}.startsWith("= Summe Materialaufwand")||
$F{Name}.startsWith("Personalaufwand")||
$F{Name}.startsWith("= Summe Personalaufwand")||
$F{Name}.startsWith("Sonstige betriebliche Aufwendungen")||
$F{Name}.startsWith("= Summe sonstige betriebliche Aufwendungen")
</source>

)

))?"true":"false"


=== Zellen fixieren ===

In Jaspersoft Studio können Sie festlegen, dass beim Excel-Export bestimmte Zeilen und Spalten fixiert werden, indem Sie spezielle Eigenschaften für den Export konfigurieren.

Um Zeilen und Spalten in Excel zu fixieren, müssen Sie die Eigenschaften

<source lang="text">
net.sf.jasperreports.export.xls.freeze.row
</source>

und

<source lang="text">
net.sf.jasperreports.export.xls.freeze.column
</source>

konfigurieren.

Wenn Sie möchten, dass die erste Zeile und die erste Spalte fixiert werden:

<source lang="text">
* net.sf.jasperreports.export.xls.freeze.row = 2
* net.sf.jasperreports.export.xls.freeze.column = B
</source>

Nach dem Export werden in Excel die erste Zeile und die erste Spalte fixiert, und der Rest des Arbeitsblatts bleibt scrollbar.

<source lang="xml">
<property name="net.sf.jasperreports.export.xls.freeze.column" value="B"/>
<property name="net.sf.jasperreports.export.xls.freeze.row" value="2"/>
</source>


=== Hintergrund- oder Textfarben beim Excel-Export ===

Beim Excel Export werden Zellen, die ein Rechteck mit einer Print-When-Expression zugewiesen bekommen haben, u.U. nicht richtig wiedergegeben, während es beim PDF Export klappt. Um dies zu beheben müssen Sie

1. den Farbraum beim Excel Export erweitern: Excel unterstützt bei Hintergrund- oder Vordergrundfarben nur wenige [http://dmcritchie.mvps.org/excel/colors.htm Farbcodes]. Für spezielle Farben nach RGB-Wert muss die Berichts-property

<source lang="xml">
<property name="net.sf.jasperreports.export.xls.create.custom.palette" value="true"/>
</source>

gesetzet werden (benötigt Bibliothek org-netbeans-core.jar im Classpath der Anwendung)

2. Statt farbiger Textfelder oder Rechtecke mit "Print-When-Expression" müssen Sie [[Berichtsdesign_mit_JasperReports#Conditional styles – Bedingte Formatierung|Conditional Styles]] nutzen.

3. Wenn Sie mit Hintergrundfarben arbeiten, müssen die Textfelder und die jew. Styles die Eigenschaft "Opaque"="true" haben.

4. Beim Export nach Excel müssen Sie das JExcelApi nutzen. Dies ist bei SuperX seit Kernmodul 4.5 der Standard, bei HISinOne-BI seit Version 7.1.


=== Seitenkopf und Seitenfuß bei Excel unterdrücken ===

Wenn Ihr Bericht normalerweise ein Band "Page Header" bzw. "Page Footer" hat, können Sie dies beim Exportformat XLS unterdrücken (z.B. wenn Sie dort keine Seitenzahlen wünschen, bei PDF aber schon).

Setzen Sie dazu die Berichts-Property

<source lang="xml">
<property name="net.sf.jasperreports.export.xls.exclude.origin.band.1" value="pageHeader"/>
<property name="net.sf.jasperreports.export.xls.exclude.origin.band.2" value="pageFooter"/>
</source>

Beim Ausgabeformat XLSX heißen die Properties:

<source lang="xml">
<property name="net.sf.jasperreports.export.xlsx.exclude.origin.band.1" value="pageHeader"/>
<property name="net.sf.jasperreports.export.xlsx.exclude.origin.band.2" value="pageFooter"/>
</source>

Dies klappt ab JR Version 4.5, sie können diese Properties aber lediglich im XML-Quellcode hinzufügen.


== Dimension Tausend-Euro ==

In Excel als Dimension Tausend-Euro ausgeben, mit zwei Nachkommastellen

In Deutschem Excel bei manueller Angabe benutzerdefiniertes Format #.##0,00.

In Jasper muss Amerikanische Vorlage sein:

-> #,##0.00

Bei Excel kann man als Property Expresion net.sf.jasperreports.export.xls.pattern z.B. nehmen

#, → zeigt nur Tausender Werte an

<source lang="text">
#,##0.00,
</source>
→ zeigt Tausernder Werte, mit zwei Nachkommastellen an

der Werte selber ist einfach $F{Soll}

Bei PDF/HTML muss man den Wert duch 1000 teilen $F{Soll}.doubleValue()/1000

und dann als Pattern z.B. #,##0.00;-#,##0.00

Die Rundung macht das Pattern.


= Nutzung in Edustore =


== Berichtsentwicklung bei Grunddaten und Basisberichten ==


=== Allgemein ===

In den Grunddaten- und Basisberichten kann man beliebige Ergebnistabellen lokal als XML speichern, und dann als Datenquelle in JasperReports einbinden. Dann kann man den Bericht lokal gestalten, und, wenn er fertig ist, in die Weboberfläche einhängen. Die XML Datei wird nur für die Testausgabe bei JasperReports verwendet und dient als Ersatz der Datenbank. Wenn der Bericht in der Weboberfläche eingehängt ist, wird dieser direkt mit frischen Daten versorgt.

Für die Folgenden 2 Punkte „Datenquelle erzeugen“ und „Template erzeugen“ gibt es [http://www.superx-projekt.de/doku/benutzerhandbuch/movies/jasper_erzeugen.viewlet/jasper_erzeugen_viewlet_swf.html hier] einen Kurzfilm.

[[Datei:JasperReports-Handbuch_vergleich_jrxml_xml_zusammen.png]]


=== Datenquelle erzeugen ===

Wenn die Ergebnistabelle eines Berichtes vorliegt, erhält man über den XML Export von SuperX die Datenquelle für den Jasper Report.

[[Datei:JasperReports-Handbuch_iReport-Datasource_erstellen.jpg]]

Diese Datei speichert man lokal ab: Wenn das Ergebnis im Browser geöffnet wurde muss man sich den Quelltext der Seite anzeigen lassen, den Quelltext komplett markieren und kopieren ( Tastenkombination Strg + a und dann Strg + c), in einen UTF-8-fähigen Texteditor einfügen (Strg + v) und dann als eine xml-Datei abspeichern.

Falls der Tomcat in ISO Kodierung läuft, muss für JasperReports in der ersten Zeile bei encoding ein UTF-8 eingetragen werden.

Beispiel:

<source lang="xml">
<?xml version="1.0" encoding="ISO-8859-1"?>
</source>

wird ersetzt mit:

<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
</source>

In JasperReports sind dann folgende Schritte zu tun, um die neue Datenquelle einzubinden.


==== Datenquelle in JasperSoft Studio ====

Die Datenquellen heißen hier "Data Adapters" und werden im Repository hinzugefügt:

[[Datei:JasperReports-Handbuch_jaspersoft_datasource1.png]]

<blockquote>Achtung: wenn Sie JasperSoft in Ihrem vorhandenen Eclipse als Plugin installiert haben, sehen Sie den Reiter "Repository" nicht; in diesem Fall liegen die Data Adapter im jew. Projekt.
</blockquote>
Im Assistenten geben Sie XML-Document als Datentyp an, und im nächsten Reiter spezifizieren Sie das Format:

[[Datei:JasperReports-Handbuch_jaspersoft_datasource2.png]]

Das Datumsformat ist bei Edustore das deutsche Schema "dd.MM.yyyy", und das Zahlenformat ist eine Zahl mit 6 Nachkommastellen und "." als Dezimaltrenner, also "#0.######". Bei Locale müssen Sie "Englisch" angeben, weil Dezimalzahlen in den Edustore-XML-Quellen den "." als Dezimaltrenner haben.

Wichtig ist auch das Ankreuzfeld "Use the report Xpath expression", dies müssen Sie immer ankreuzen.


==== Datenquelle in iReport ====

Klick auf „Report Datasources“. Es öffnet sich ein Fenster, in dem die vorhandenen Datenquellen angezeigt werden.

[[Datei:JasperReports-Handbuch_iReport-Datasource_1.jpg]]

In diesem Fenster Klickt man auf „New“ um eine neue Datenquelle anzulegen.

[[Datei:JasperReports-Handbuch_iReport-Datasource_2.jpg]]

Nun wählt man „XML file datasource“ aus und klickt auf „Weiter“.

[[Datei:JasperReports-Handbuch_iReport-Datasource_3.jpg]]

Im letzten Schritt wählt man einen Eindeutigen Namen aus, der auch später in dem Dropdown Menü erscheint, gibt den Dateipfad an und ändert die restlichen Einstellungen wie im Screenshot.

[[Datei:JasperReports-Handbuch_iReport-Datasource_4.jpg]]

Die Formate für Datum und Nummer müssen angegeben werden, da sonst die amerikanischen angenommen werden. Bei Locale müssen Sie "Englisch" angeben, weil Dezimalzahlen in den Edustore-XML-Quellen den "." als Dezimaltrenner haben.

<blockquote>Hinweis: in JasperReports 3.7.1 werden trotz des korrekten Zahlenformats die Dezimalstellen von Beträgen immer mit ",00" wiedergegeben. Dies liegt an der "Locale", man muss diese auf "Englisch" umstellen. Das Problem ist allerdings: sobald man das macht, kann man die XML-Datenquelle in der Datenquellenverwaltung nicht mehr ändern, d.h. man muss sie bei Änderungen löschen und neu einfügen.
</blockquote>
Nach dem Speichern erscheint die Datenquelle im dropdown Menü und kann ausgewählt werden. Damit man die Datenquelle nutzen kann, braucht man auch noch ein Template.


=== Template erzeugen ===

Um ein leeres Template zu erzeugen, geht man wieder in die Ergebnistabelle der selben Maske, deren Datenquelle erstellt wurde, wählt im Dropdown Menü neben „Bericht entwerfen“ „Leerer Bericht“ aus und klickt auf das Icon daneben „Export als JasperReport-Template“.

[[Datei:JasperReports-Handbuch_iReport-leeren_Bericht_erstellen.jpg]]

Diese Datei speichert man Lokal ab. Wenn das Ergebnis im Browser geöffnet wurde muss man sich den Quelltext der Seite anzeigen lassen, den Quelltext komplett markieren und kopieren ( Tastenkombination Strg + a und dann Strg + c), in einen UTF-8-fähigen Texteditor einfügen (Strg + v) und dann als eine jrxml Datei abspeichern. JR in der Endung jrxml steht für JasperReports. Damit können die Datenquellen und die Templates unterschieden werden und sogar den selben Dateinamen tragen (nur unterschiedliche Dateiendung).

Sie sollten es sich nicht zumuten und versuchen über JasperReports einen neuen Bericht zu entwerfen. Nehmen Sie immer den "leeren" Bericht aus der entsprechende Maske, da dort sehr viele Kleinigkeiten voreingestellt sind. Sie sparen sich damit immens viel Arbeit.


=== Template einbinden ===


==== Reportdesign verlinken ====

Um das erstellte Template einzubinden, muss zunächst die jrxml Datei in das Verzeichnis webapps/superx/WEB-INF/reports kopiert werden. Danach muss das Stylesheet im System bekannt gegeben werden. In Grunddaten und Basisberichte geht man dazu in „Administration“ → „Masken“ → „Stylesheet suchen“ und schickt die Maske so ab. Danach klickt man bei einem beliebigen Stylesheet auf den „bearbeiten“ Button ganz rechts in der Tabelle.

[[Datei:JasperReports-Handbuch_iReport-Stylesheet_1.jpg]]

Klickt dann auf „Neuen Datensatz erzeugen“.

[[Datei:JasperReports-Handbuch_iReport-Stylesheet_2.jpg]]

In Dateiname kommt der Dateiname der jrxml Datei rein, welche sich in dem reports Ordner befindet. Beschriftung und Beschreibung sollte eindeutig dem Stylesheet zuzuordnen sein. Für JasperReport wählt man bei „Tabelle oder Maske“ „Stylesheet für eine Ergebnistabelle“ aus. Der Dateityp stellt das default Ausgabeformat fest.

Um dieses Stylesheet nun einer Maske zuzuordnen, geht man in die Maske „Administration“ → „Masken“ → „Maske suchen“, sucht in dem Feld „Maske“ die gewünschte Maske aus und klickt dann auf „Abschicken“. Nun klickt man auf den Button Stylesheets neben der Maske, der das neue Stylesheet zugeordnet werden soll.

[[Datei:JasperReports-Handbuch_iReport-Stylesheet_3.jpg]]

In dem neuen Fenster wählt man das neu erstellte Stylesheet aus und speichert diese Einstellung ab.

[[Datei:JasperReports-Handbuch_iReport-Stylesheet_4.jpg]]

Damit ist der Bericht der Maske zugeordnet.

<blockquote>Normal wird im Servlet direkt vom Berichtsergebnis nach JasperReports übergeben, d.h. ohne den Zwischenweg XML. Wenn aber im Dateinamen *_xmlsource.jrxml steht, wird Datenquelle XML erzwungen (für Makroberichte, Unterberichte, Subdatasets oder spezielle XPATH-Selektionen wichtig).
</blockquote>

==== Nutzung des Upload Servlets ====

Wenn Sie keinen Schreibzugriff auf den Ordner ''WEB-INF/reports'' haben, können Sie auch Templates über das [http://www.superx-projekt.de/doku/kern_modul/admin/f_Anpassungderwebxml.htm Upload Servlet ]direkt im Browser hochladen. Dazu müssen Sie in der web.xml die Dateiendungen .jrxml und (sofern benötigt) .jasper erlauben, siehe obiger Link.

Danach können Sie die Report Templates hochladen:

[[Datei:JasperReports-Handbuch_jr_upload1.png]]

Nach dem Upload können Sie das Template zunächst registrieren:

[[Datei:JasperReports-Handbuch_jr_upload2.png]]

und dann der jew. Maske zuordnen. Beachten Sie, dass der Pfadname relativ zum Ordner WEB-INF/reports angegeben wird, also in der Regel

../../default/custom

bzw. beim Mandantenbetrieb

../../Mandant-ID/custom


==== Probleme beim Deployment im Server ====

Es kann u.U. beim Deployment eines Berichts im Server das Problem auftreten, daß ein Bericht im lokalen iReport mit der XML-Datenquelle funktioniert, aber im Server für einzelne Merkmale kein Ergebnis geliefert wird. Dies hat folgende Ursache:


===== Feldnamen im Berichtsdesign weichen vom Datenbank-Feldnamen ab =====

Bei der lokalen Entwicklung in iReport werden die Berichte mit der Datenquelle XML erzeugt. In den Muster-JRXML-Dateien, die man über das Feld "Bericht erzeugen" generiert, sind die Felder über die folgende Notation deklariert:

<source lang="xml">
<field name="Fakultät/Fachbereich (Schlüssel)" class="java.lang.String">
<fieldDescription><![CDATA[col[@id="4" and wert!=""]/wert]]></fieldDescription>
</field>
</source>

Dies bedeutet: Das Feld "Fakultät/Fachbereich (Schlüssel)" hat den Typ "String" und befindet sich im XML-Datenstrom in der vierten Spalte (col@id=4). Dabei befindet sich in Datenblattberichten im Spaltennamen immer ein "\n" vor der Zeichenkette "(Schlüssel)", um einen Zeilenumbruch im generischen Standardlayout zu erzeugen. Dieses "\n" wird dann für iReport und JasperReports automatisch durch ein Leerzeichen ersetzt.

Wenn die XML-Datenquelle nicht verändert wird, dann ist das Feld immer mit dem gleichen Inhalt gefüllt.

Wenn man den Bericht dann auf den Server kopiert und einbindet, ohne im Dateinamen "_xmlsource" zu verwenden, dann wird das Feld nicht über die Spaltennummer identifiziert, sondern über den Feldnamen, hier z.B. "Fakultät/Fachbereich (Schlüssel)". Das bedeutet, daß der Server genau diesen Feldnamen zurückliefern muss. Das kann u.U. abweichen:

* Der Server bzw. die zugrunde liegende Maske wurde verändert, so daß der Feldname geringfügig anders ist. Das sollte eigentlich nicht passieren, kann aber vorkommen.
* Beim Betrieb in HISinOne gibt es in allen Versionen bis 3.02 noch eine kleine Veränderung, wenn das Modul des zugrunde liegenden Datenblattberichts bzw. der Maske direkt per Tomcat-Start installiert wurde, und nicht in dem Edustore-Installation/Upgrade-Menü. Wenn die Module beim Tomcat Start in eine leere Datenbank installiert werden, dann werden Zeichenketten mit dem Feldinhalt "\n" verfremdet nach "n" (also der "\" wird entfernt). Das führt dann dazu, daß das Feld ohne den "\" in der jrxml-Datei deklariert wird, also z.B.

<source lang="xml">
<field name="Fakultät/Fachbereichn(Schlüssel)" class="java.lang.String">
<fieldDescription><![CDATA[col[@id="4" and wert!=""]/wert]]></fieldDescription>
</field>
</source>

Wenn man danach dann einen Upgrade der jew. Komponente ausführt, dann wird die Spalte in der Maske umbenannt nach "Fakultät/Fachbereich'''\n'''(Schlüssel)" und der Feldname korrekt nach "Fakultät/Fachbereich''' '''(Schlüssel)" umgesetzt. Durch das "n" vor der Zeichenkette "(Schlüssel)" paßt der Feldname in der jrxml-Datei nicht mehr zum Ergebnis aus der Datenbank, und das Feld ist leer. So kann es passieren, daß ein Bericht in iReport funktioniert, im Server aber nicht. Im folgenden die Lösung.


===== Korrektur der Feldnamen im Berichtsdesign =====

Um sicherzustellen, dass der Feldname der jrxml-Datei mit der jeweils aktuell benutzten Datenbank-Version übereinstimmt, geht man wie folgt vor:

* Erzeugen Sie in Edustore eine HTML-Ausgabe der zugrunde liegenden Abfrage, bei Datenblatt-Berichten ist dies das "generische Standardlayout".
* Klicken Sie dann oben im Berichtskopf auf den Button "Bericht entwerfen" -> "leerer Bericht"
* Im Quellcode sehen Sie die Zeilen <field name="Berichtsname" class="java.lang.String"> ... Hier ist jedes einzelne Feld aus der Datenbank deklariert.
* Markieren Sie alle Zeilen bis zum letzten "<field...>"-Element, i.d.R. ist dies das Feld <field name="user"..., und kopieren Sie dies in die Zwischenablage
* Öffnen Sie die jrxml-Datei mit einem UTF-8-fähigen Editor, z.B. Jedit.
* Ersetzen Sie genau die "<field..."-Passage aus der Zwischenablage.
* Speichern Sie den Bericht, und testen Sie die Vorschau in JasperReports. Wahrscheinlich kommt eine Fehlermeldung "Field ... does not exist" o.ä., dann müssen Sie das Feld mit Suchen->Ersetzen umbenennen.
* Das machen Sie so lange, bis die Vorschau funktioniert. Danach können Sie die jrxml-Datei wieder auf den Server kopieren. Die Felddeklaration passt dann zum Server.


== Zuordnung von Default-Feldbelegungen zu Stylesheets ==

Es können für Stylesheets Default-Feldbelegungen für Stylesheets hinterlegt werden. Hintergrund dieser Funktion ist, dass bei speziellen Stylesheets standardmäßig beliebig viele Spalten vorbelegt werden können. In Datenblattberichten gibt es z.B. das Feld "Felder", in dem die auszugebenden Spalten angegeben werden. Aus Performancegründen sollten nur die Spalten ausgegeben werden, die auch benötigt werden. So kann dann z.B.für JasperReport Stylesheets hinterlegt werden können, welche Spalten auf jeden Fall benötigt werden. Der Anwender weiß nicht welche Spalten benötigt werden und würde im Normalfall alle Spalten ausgeben lassen um keine Fehlermeldung zu erhalten. Dadurch würde aber wiederum der Bericht unnötig lange dauern, da alle Spalten berechnet werden müssen, auch die, welche nicht benötigt werden.

Wenn Sie ein Stylesheet erstellt haben und dieses in SuperX eingebunden haben gehen Sie wie folgt vor:

Sie gehen in die Maske "Administration -> Tabelle suchen", geben dort bei Stichwort "stylesheet_field" ein und schicken die Maske ab.

[[Datei:JasperReports-Handbuch_stylesheet_field_maske.png]]

In der folgenden Ergebnistabelle klicken Sie bei "stylesheet_field_list" auf den "Bearbeiten" Button.

[[Datei:JasperReports-Handbuch_stylesheet_field_tabelle.png]]

In dem nun geöffneten Fenster sehen Sie alle Zuordnungen, welche bereits eingetragen sind. Hier wird aber lediglich das Stylesheet ausgegeben und nicht die Tabellen und Federzugehörigkeit. Dies hätte wegen der vielen Auswahlmöglichkeiten jeden Browser gekillt. Um Einzelheiten zu erfahren müssen Sie daher auf den Details-Button klicken. Auch wenn Sie eine neue Zuordnung erstellen möchten klicken Sie zunächst auf den Detail-Button eines beliebigen Stylesheets.

[[Datei:JasperReports-Handbuch_stylesheet_field_list.png]]

Jetzt können Sie die Zugehörigkeit des Stylesheets zu Tabelle und Feld ändern oder eine neue Zuordnung erstellen.

Achtung: Wenn ein Tabellenname ausgewählt und abgespeichert wurde, können nur Spalten dieser Tabelle ausgewählt werden. Wenn Sie die Tabelle ändern wollen, müssten Sie zunächst die Tabelle ändern, abspeichern und dieses Formular erneut aufrufen. Erst dann würden die Spalten der ausgewählten Tabelle in der Listbox Fieldname erscheinen.

[[Datei:JasperReports-Handbuch_stylesheet_field_edit.png]]

Um eine neue Verknüpfung zu erstellen klicken Sie zuerst auf den + Button oben rechts. Danach erscheint das gleiche Formular nur ohne ausgefüllte Felder. Hier können Sie das Stylesheet und den Tabellennamen auswählen und die dazu passende Spalte der Tabelle die Sie zuvor ausgewählt haben. Achten Sie darauf die Tabelle zu nehmen, welche im Datenblatt verwendet wird. Danach nur noch über das Diskettensymbol oben rechts abspeichern und eine Spalten-Stylesheet-Verknüpfung ist fertig. Diesen Schritt wiederholen Sie für jede Spalte, die Sie in dem JasperReport Bericht benötigen.

Ab Kernmodul 4.2 bzw. HISinOne 5.1 geht es noch komfortabler, Sie können hier auf einzelne Stylesheets filtern : Administration → Masken → Stylesheet suchen

Wählen Sie zunächst den Bericht aus, und klicken Sie dann rechts beim Bearbeiten-Button in der Spalte Felder-Vorbelegungen bearbeiten:

[[Datei:JasperReports-Handbuch_stylesheet_field.png]]

In dem Bearbeitungsformular können Sie Datensätze erzeuge, löschen etc.


== Kurzanleitung Direktaufruf von Jasper-Berichten von der Maske ==

Nach dem Abschicken der Maske kann man auch direkt auf den entsprechenden Jasper-Bericht umgeleitet werden. Es muss dazu in der Maske ein Feld geben mit dem Namen

<source lang="text">
tablestylesheet
</source>

und der relation

<source lang="sql">
<<SQL>> select distinct filename,X.caption from sx_stylesheets X,
sx_mask_style S where X.tid=S.stylesheet_id and S.maskeninfo_id=23880
</source>

und zum Beispiel für Default der Maske 23880

<source lang="sql">
<<SQL>> select distinct filename,X.caption from sx_stylesheets X,sx_mask_style S where X.tid=S.stylesheet_id and S.maskeninfo_id=23880 and S.ord=2
</source>

Für die Anzeige des Feldes tablestylesheet im Browser wird eine Berschriftung caption hinterlegt, damit auf der Maske "Bericht" erscheint. Im neuen Kern-Modul passiert dies automatisch.

Es ist möglich einen manuellen Eintrag in die Tabelle ''sx_captions'' einzufügen (siehe Maske Administration -> Maske -> Beschriftung suchen).

{| class="wikitable"
|-
!
!
!
!
!
|-
| tid
| table_name
| field_name
| locale
| contents_short
|-
| <<wird automat. vergeben>>
| felderinfo
| tablestylesheet
| de
| Bericht
|}

Außerdem muss man die Maske um ein Feld Ausgabeformat ergänzen, das die Art=1 hat und folgende relation:

<source lang="sql">
select element_value,description from menu_element where element='Ausgabeformat' and nature::smallint<100 order by nature::smallint
</source>

Beispiel für Default Excel:

<source lang="sql">
<<SQL>> select element_value,description from menu_element where element='Ausgabeformat' and description='Excel'
</source>

Achtung: Hier kommen erst Ergebnisse, wenn Sie das Kernmodul 4.1 / HISinOne 3.0 oder höher installieren.


== Spezielle Variablen ==

Im Berichtsdesign können neben den Feldern der Ergebnistabelle auch z.B. der Berichtsname, Erleuterung, user und standdatum benutzt werden. Zu finden sind diese im "Report Inspector" unter Fields. Um auch Hochschulspezifische Informationen wie Hochschulname oder Hochschul-Webadresse in einen Bericht importieren zu können wurden unter anderem die sx_captions Variablen "REPORT_HEADING_INSTITUTION" und "REPORT_HEADING_URL" integriert.

[[Datei:JasperReports-Handbuch_sx_captions_markiert.png]]

Diese können genau wie die anderen Fields in den Bericht per Drag&Drop gezogen werden.


== Makroberichte als Datenquelle für JasperReports ==

Sie können als Datenquelle für JR nicht nur einzelne Masken nehmen, sondern auch die Ausgabe von Makro-Masken. Dadurch können die verschiedenartigsten Informationen aus den normalen Masken für übergreifende Berichte genutzt werden.

Das folgende Beispiel zeigt, wie im KLR-Bericht "Berichtsblatt: Kennzahlen aus der Kostenrechnung" Teile verwendet werden, um einen eigenen JR zu erzeugen, der wiederum Elemente des Makroberichts als Unterbericht nutzt.

Zunächst rufen Sie den Makrobericht auf:

[[Datei:JasperReports-Handbuch_makro_html.png]]

Das Bild zeigt die ersten drei Elemente des Makros, sie werden mit einer Ordnungsnummer durchnummeriert.

Wir laden dazu die XML-Datenquelle herunter, die XML-Datenquelle binden wir wie [[Berichtsdesign_mit_JasperReports#Datenquelle erzeugen|gewohnt]] in JasperReports ein:

[[Datei:JasperReports-Handbuch_makro_datenquelle.png]]

Dann klicken wir im Browser über den Tabellen den Button rechts von "Bericht entwerfen" → Leerer Bericht. Die JRXML-Datei speichern wir wie [[Berichtsdesign_mit_JasperReports#Template erzeugen|gewohnt]].

Im Designer sehen wir nun bei den Feldern eine erweiterte Liste:

[[Datei:JasperReports-Handbuch_makro_jrxml.png]]

Wir sehen also, daß die Ergebnisspalten mit einem Präfix für die Tabellennummer versehen sind, z.B. "tab_0". Dadurch können wir die Tabellen und somit auch die jew. Spalten eindeutig identifizieren. Dies ist gleichzeitig der Hauptbericht. Das Detail-Band löschen wir (ist nicht nutzbar), stattdessen aktivieren wir ein Summary Band.

Dann erzeugen wir den [[Berichtsdesign_mit_JasperReports#Unterberichte|Unterbericht]] für Studierenden-VZÄ. Dazu speichern wir die obige jrxml-Datei z.B. mit dem Namen makro_beispiel_ub_stud.jrxml und entfernen das Titel-Band und Seitenfuß-Band. Dann fügen wir im Designer einen Parameter "ordnr" hinzu:

[[Datei:JasperReports-Handbuch_makro_ub_param.png]]

Der Unterbericht bekommt dann in der Report Query folgende Änderung:

[[Datei:JasperReports-Handbuch_makro_ub_report_query.png]]

Die Ordnungsnummer wird vom Hauptbericht übergeben und dient dazu, in der XML-Datenquelle auf die einzelne Tabelle zu filtern.

Zusätzlich geben wir noch einen weiteren Filter ein, damit die Summenzeilen aus der Originaltabelle nicht in die Kreuztabelle aufgenommen werden:

[[Datei:JasperReports-Handbuch_makro_ub_filter.png]]

Damit der Unterbericht auch "stand-alone" ausführbar ist, können Sie dem Parameter "ordnr" auch einen Standardwert zuweisen, hier z.B. "2":

[[Datei:JasperReports-Handbuch_makro_ub_ordnr_default.png]]

Nun können wir die [[Berichtsdesign_mit_JasperReports#Unterberichte|Kreuztabelle]] mit dem Assistenten erzeugen. Für unser Beispiel enthält die Kreuztabelle Studierenden-VZÄ nach Studiengang und Fachkennzeichen:

[[Datei:JasperReports-Handbuch_makro_ub_crosstab.png]]

Wir speichern den Unterbericht und binden ihn in den Hauptbericht im Summary Band ein. Dabei vergeben wir wie gewohnt die Parameter XML_LOCALE und XML_NUMBER_PATTERN. Außerdem erzeugen wir den Parameter "ordnr", und weisen diesem den Wert 2 zu, weil die Studierenden-Tabelle die Ordnungsnummer 2 hat (s.o.):

[[Datei:JasperReports-Handbuch_makro_hauptbericht_ub_params.png]]

Damit ist die Konfiguration beendet, der Bericht sieht so aus:

[[Datei:JasperReports-Handbuch_makro_hb_erg.png]]

Weitere Unterberichte lassen sich analog hinzufügen.

<blockquote>Hinweis zum Einbinden im Servlet: Unterberichte arbeiten nur mit der Datenquelle XML, daher müssen Sie die Datei des Hauptberichts mit dem Suffix "_xmlsource" versehen.
</blockquote>


== Kompatibilität von iReport mit JasperReports ==

Wenn Sie mit iReport Berichte erzeugen, sollte wie gesagt die iReport-Versionsnr. mit der JasperReports-Version übereinstimmen, die der jew. Server nutzt. In Edustore ist dies derzeit die Version 5.1.0. Wenn die Versionsnummern nicht übereinstimmen, dürfen Sie keinesfalls die *.jasper-Dateien von dem lokalen Arbeitsplatz zum Tomcat Server kopieren.

Darüber hinaus kann es auch weitere Abhängigkeiten geben, iReport bringt ein paar mehr Bibliotheken mit, als JasperReports. Wenn Sie dann eine jrxml-Datei auf den Server kopieren, könnte es eine Fehlermeldung geben in dem Stil

<source lang="text">
java.lang.NoSuchMethodError:...
</source>

Das Vorgehen ist hier wie folgt:

* Prüfen Sie zunächst, ob Sie die jeweilige Bibliothek wirklich brauchen.
* Wenn ja, dann ermitteln Sie aus dem Namen der fehlenden Klasse den Namen der *.jar-Datei. Meist reicht es, wenn Sie den Klassennamen in einer Suchmaschine eingeben, oder in einer speziellen Java-Suchmaschine wie http://www.jarfinder.com/
* Wenn Sie die jar-Datei identifiziert haben, können Sie diese von iReport-xxx/ireport/modules/ext/ in das webapps/superx/WEB-INF/lib Verzeichns kopieren.
* Danach müssen Sie Tomcat neu starten.

<blockquote>Achtung: gehen Sie beim Kopieren in den WEB-INF/lib Ordner möglichst '''sparsam''' um: manchmal gibt es zwischen einzelnen Bibliotheken unerwünschte und unvorhersehbare Querabhängigkeiten, z.B. nutzt eine iReport-Bibliothek xy.jar eine andere Bibliothek vz.jar, welche bereits im Tomcat Server vorhanden ist – aber mit einer anderen Versionsnummer. In diesem Falle kann es zu seltsamen Phänomenen kommen, die sehr schwer zu diagnostizieren sind, bis hin zu einer Instabilität des Servers. Man muss solche Kopiermaßnahmen auf jeden Fall gründlich testen! 
Unter uns: Wir nennen Probleme, die dadurch entstehen können, die "jar-Hölle"...
</blockquote>
Im folgenden sammeln wir ein paar Beispiele für gefahrlose Kopieraktionen.


==== iReport Grafiken in JasperReports ====

Bitte vermeiden Sie, iReport-spezifische "Themes" zu benutzen (z.B. "aegean"), denn dafür würden weitere Bibliotheken benötigt. Wenn Sie z.B. die folgende Fehlermeldung bekommen, wurde ein Theme benutzt:

[[Datei:JasperReports-Handbuch_grafik_theme_error.png]]

Dann sollten Sie die Einstellung für das Objekt (hier das Theme der Grafik) wieder auf default setzen.


==== Weitere Bibliotheken von iReport ====

Bei der Meldung

<source lang="text">
java.lang.NoSuchMethodError: org.objectweb.asm.ClassWriter
</source>

sollten Sie die Bibliotheken

<source lang="text">
iReport-xxx/ireport/modules/ext/asm.jar
</source>

und zur Sicherheit auch

<source lang="text">
asm-attrs.jar
</source>

in den WEB-INF/lib-Ordner kopieren.


= Troubleshooting =


== Report Problem: Class not set for bucket: <<Variable>> ==

Das Problem tritt in iReport 4.1.1 u.a. bei Kreuztabellen auf. Bei diesem Fehler fehlt in der jrxml-datei im Element <bucketExpression> Z.B.: class="java.lang.String". Diese einfach im Editor ergänzen und es funktioniert. Beispiel:

Aus :

<source lang="xml">
<bucketExpression>
</source>

wird:

<source lang="xml">
<bucketExpression class="java.lang.String">
</source>


== Die jasper Datei ==

Die jasper Datei ist die kompilierte jrxml. Wenn ein Bericht übertragen werden soll, z.B. von dem Entwickler auf den Server oder von dem Development System auch das Produktivsystem immer nur die jrxml Datei übertragen, da es bei Versionsunterschieden in JasperReport zu Fehlern kommt, wenn die Kompilierte Version zur Verfügung steht. Sobald der Bericht ausgeführt wird, erstellt (kompilliert) JasperReports automatisch die jasper Datei.

Wenn die jasper Datei zur verfügung steht, wird auch nur noch diese von JasperReports verwendet und nicht mehr neu kompiliert. Falls Sie also einen Bericht weiter entwickelt haben oder eine neue Version einspielen, löschen Sie direkt die jasper Datei. Ansonsten werden die Änderungen nicht wirksam.


== Im Excel Export fehlen Felder ==

In Excel werden überlappende Elemente nicht angezeigt. Wenn also 2 Elemente übereinander liegen wird in Excel nur das oberste (welches im Vordergrund liegt) angezeigt. Hier ist besonders drauf zu achten, dass visuell 1px Abstand zwischen den Elementen Platz ist. Wenn von beiden Elementen jeweils eine Linie zu sehen ist, ist es korrekt. Wenn nicht, zählt das schon als Überlappung. Dafür im iReport Designer am besten ganz nah heran zoomen um diesen Abstand zu prüfen.

Hier ein Beispiel. Die beiden oberen Elemente überlappen, die unteren nicht:

[[Datei:JasperReports-Handbuch_ireport_excel.png]]


== Hinweis für HisInOne 7.0 Kompatibilität ==

Jrxml-Dateien, die unter iReport 4.1.3 entwickelt wurden und in HisInOne 7.1 funktionieren, können in 7.0. zur Fehlermeldung führen:

<source lang="text">
java.lang.NoClassDefFoundError: net/sf/jasperreports/compilers/GroovyEvaluator
</source>

In der jasperreports5.1.0 (hisinone 7.0) ist die Klasse GroovyEvaluator nicht enthalten, für 7.1 ist die jasperreports-6.1.0.jar enthalten, die enthält den GroovyEvaluator.

Workaround:

<source lang="text">
language="groovy"
</source>

ändern in

<source lang="text">
language="java"
</source>


== HTML Export keinen whitespace ==

Normal macht JR bei HTML-Exporten für den „Seitenumbruch“ eine Reihe von Leerzeilen. Um dies zu vermeiden, setzen Sie die Property IgnorePagination=true:

<source lang="xml">
<jasperReport xmlns="http://jasperreports.sourceforge.net/jasperreports" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://jasperreports.sourceforge.net/jasperreports http://jasperreports.sourceforge.net/xsd/jasperreport.xsd" name="Kaufm. Quartalsbericht" language="groovy" pageWidth="2925" pageHeight="565" orientation="Landscape" columnWidth="2925" leftMargin="0" rightMargin="0" topMargin="0" bottomMargin="0"
</source>

isIgnorePagination="true">


== UUID's ==

In Jaspersoft Studio wird an jedes Element eine lange UUID angehängt, in aktuellen Versionen von SuperX/ Edustore macht das keine Probleme. In älteren Versionen bzw. in iReport 4.* schon. Damit der JasperReport abwärtskompatibel ist, muss diese gelöscht werden. Bei großen Berichten taucht diese aber unter Umständen mehrere hundert Mal auf. Hier kann in JasperSoft Studio in dem "Source"-Reiter des Berichtsdesigners nach folgender Regular Expression gesucht werden und diese mit einem Leerzeichen ersetzt werden:

<source lang="text">
uuid="[0-9a-z-]{36}"
</source>


= Weitere Dokus =

<blockquote>Ahammad, S. (2010). iReport 3.7.Learn how to use iReport to create, format, and export reports. Birmingham: Packt
</blockquote>
<blockquote>Haneke, U. et al. (2010). Open Source Business Intelligence. Möglichkeiten, Chancen und Risiken quelloffener BI-Lösungen. Wien: Hanser
</blockquote>
<blockquote>Toffoli, G. (2007). The definitive guide to iReport. Berkeley, CA: Apress
</blockquote>
<blockquote>Noch mehr Infos (nur Englisch) erhält man unter: 
http://jasperforge.org/plugins/project/project_home.php?projectname=ireport
</blockquote>
<blockquote>und natürlich unsere Website:
</blockquote>
<blockquote>http://www.superx-projekt.de/doku/entwicklung/iReport-Handbuch/main.htm
</blockquote>
<blockquote>
</blockquote>

Berichtsdesign mit JasperReports

2026-07-06T07:59:40Z

Andrek: /* Zellschutz aktivieren */

Berichtsdesign mit JasperReports

von Daniel Quathamer & Andre Knieschewski


= JasperReports installieren und konfigurieren =


== Voraussetzungen ==

* Jasperreports ist eine Laufzeitumgebung fürs Reporting, die in java-basierte Reporting Software integriert werden kann. Der Download ist hier: https://sourceforge.net/projects/jasperreports/. Dieses Paket enthält kommandozeilenbasierte Demos und die benötigten Libraries. Die Demos sind sehr nützlich und als Referenz gut nutzbar.
* Die Entwicklungsumgebung für JasperReports heißt "Jaspersoft Studio" und kann bezogen werden von https://community.jaspersoft.com/project/jaspersoft-studio. Es enthält auch obige Laufzeitumgebung. 
Da es ein Eclipse Plugin ist, können Sie es auch direkt in Ihrem Eclipse installieren (Menü Help → Eclipse Marketplace → Suchwort "Jaspersoft". Dort können Sie aber nur die jeweils aktuelle Version installieren.

Da der Download bei Jaspersoft nun nur für registrierte Nutzer zur Verfügung steht, hier noch ein Link für den Download: https://sourceforge.net/projects/jasperstudio/files/

* Für altere Projekte wurde auch iReport verwendet. Da es ein paar Bugs in den verschiedenen Versionen gibt, empfehlen wir zu der Erstellung von JasperReport Berichten die iReport Version 4.1.3, auch wenn in Edustore die Version 5.1.0 verwendet wird. Download der passenden Version von iReport von http://sourceforge.net/projects/ireport (dort auf "files"->"iReport" klicken, dann erhalten Sie Links auf die jeweilige Version.
* Für Demos & Deployment auch Apache ANT http://ant.apache.org/
* Java 1.8 JRE oder höher


== JasperReports und Jaspersoft Studio ==

JasperReports ist das Programm, das fertige Berichte erzeugen kann. Es besitzt (außer einer Vorschauansicht der Berichte) keine graphische Oberfläche. Für das Entwerfen von Berichten ist ''''''Jaspersoft Studio'''''' geeignet. Um es noch ein wenig zu veranschaulichen könnte man sagen, dass wenn ein JasperReport das Worddokument wäre, dann wäre Jaspersoft Studio z.B. Microsoft Word.


=== Jaspersoft Studio ===

Nach dem Download benötigen Sie Java 1.8 oder höher zum Ausführen. Nach dem Entpacken können Sie die Anwendung direkt starten.

Bei JasperSoft Studio wird als Grundlage Eclipse verwendet. Wenn man JasperSoft Studio herunter lädt, erhält man automatisch Eclipse mit dabei. JasperSoft Studio kann [http://community.jaspersoft.com/project/jaspersoft-studio hier] heruntergeladen werden.

Wenn lieber ein bereits vorhandenes Eclipse verwendet werden soll und Jaspersoft Studio dort als Plugin installiert werden soll, gibt es 2 Wege:

<ol style="list-style-type: decimal;">
<li>Unter Help → Eclipse Marketplace kann nach „Jaspersoft“ gesucht werden und das Plugin installiert werden
[[Datei:JasperReports-Handbuch_jaspersoftstudio_plugin_install1.png]]</li>
<li>Man kann auch über die Marketplace Webseite von Eclipse das Plugin Jaspersoft Studio suchen und das Icon per Drag&Drop nach Eclipse ziehen. Dann wird das Plugin automatisch installiert. [https://marketplace.eclipse.org/content/jaspersoft-studio Hier] die Webseite. (Bei mir hat das Drag&Drop leider nicht funktioniert. Das kann an Linux liegen. Unter Windows wird es sicherlich funktionieren.)</li></ol>


==== Jaspersoft Studio Einstellungen ====

Unter Windows - > Preferences → Jaspersoft Studio können Sie verschiedene Einstellungen vornehmen. Wichtig in der Menüpunkt "Compatibility": wählen Sie dort die JR-Version, die auch Ihre Ziel-Platform enthält.

Im Dateimanager von JasperSoft Studio gibt es Eclipse-typisch ein "virtuelles" Dateisystem mit dem Standardnamen "MyReports", zumindest beim Speichern von Dateien. Dieses Dateisystem liegt physisch im Ordner <<Home-Verzeichnis>>/JaspersoftWorkspace/MyReports.

Beim Öffnen von Dateien können Sie direkt mit "Open File" aufs normale Dateisystem zugreifen.


==== Jaspersoft Studio Entwurfsbereich ====

Hier eine Übersicht des Entwurfsbereichs, in rot finden Sie Erläuterungen:

[[Datei:JasperReports-Handbuch_jaspersoft_designer.png]]

Die Unterfenster können Sie Eclipse-typisch beliebig anordnen. Oben ein Beispiel.


===== Jaspersoft Studio Sortierung und Filterung der Datenquelle =====

Wenn die Datenquelle definiert ist, kann /sollte der Bericht die Sortierung und Filterung der Daten festlegen. Dies ist etwas versteckt im Designer mittig oberhalb des Entwurfsbereichs:

[[Datei:JasperReports-Handbuch_jaspersoft_design_query.png]]

Im "Dataset and Query Dialog" sind die Felder der Datenquelle aufgeführt. Unten finden Sie die Reiter "Sorting" und "Filter Expression". Dort pflegen Sie beides.


===== Jaspersoft Studio Berichtsdesign und Vorschau =====

Im Designmodus können Sie den Bericht entwerfen, oder den XML-Quellcode. Beim Klick auf den Reiter "Preview" bekommen Sie eine Vorschau des Berichts:

[[Datei:JasperReports-Handbuch_jaspersoft_design_preview.png]]

Oberhalb der Vorschau können Sie die Datenquelle (d.h. den "Data Adapter" angeben, und rechts daneben die Anwendung, die den Bericht zur Anzeige bringt ("Viewer"). Voreingestellt ist hier der Java-interne Viewer von JasperReports, Sie können den aber umstellen z.B: auf PDF oder Excel.

Mit Klick auf das grüne Dreieck führen Sie den Bericht aus und erhalten die Vorschau.

<blockquote>Achtung: Es ist aufgefallen, dass beispielsweise Fettdruck in der PDF-Vorschau nicht angezeigt wird. Im Java-Preview und aus der Weboberfläche geladen, ist der Fettdruck ersichtlich.
</blockquote>

===== Jaspersoft Studio Berichtsstruktur =====

Im "Outline View" sehen Sie die Struktur des Berichts, d.h. aktive "Bänder" und Metadaten:

[[Datei:JasperReports-Handbuch_jaspersoft_design_outline.png]]

Die Elemente unter "Fields" werden bei Nutzung in [[#3.1.3.Template erzeugen|outline|Edustore]] automatisch gefüllt. Alles weitere definieren Sie.


===== Jaspersoft Studio Elemente bearbeiten =====

Wenn Sie im Design Modus ein Element markieren, wird es automatisch im Outline und in dem Reiter "Properties" selektiert:

[[Datei:JasperReports-Handbuch_jaspersoft_design_properties.png]]

Im Outline zeigt es lediglich, wo es sich befindet, und im Reiter "Properties" können Sie Formatierung, Anzeige etc. bearbeiten.


=== iReport ===

[[Datei:JasperReports-Handbuch_welcome.png]] Das Paket enthält bereits die Laufzeitumgebung JasperReports, diese muss also nicht separat installiert werden. Nichtsdestotrotz empfiehlt sich der Download, denn in dem JasperReports-Paket befinden sich viele lehrreiche Demo-Berichte.

Die Windows-Version beinhaltet auch einen Installer. Um diesen zu nutzen sind Admin-Rechte erforderlich.

Alternativ bzw. unter Linux ist iReport ohne Installation direkt nach dem Entpacken lauffähig. Wenn Sie auch Scriptlets erstellen wollen, müssen Sie nicht nur eine Java-Laufzeitumgebung (JRE) installieren, sondern ein JDK, und die Datei $JAVA_HOME/lib/tools.jar nach iReport-<<Versionsnr.>>/ireport/libs kopieren. Danach müssen Sie iReport neu starten.

Start unter Windows: iReport-<<Versionsnr.>>/bin/ireport.exe

Start unter Linux: iReport-<<Versionsnr.>>/bin/ireport


==== iReport Einstellungen ====

Als erstes sollten Sie die Anwendungen einstellen, mit denen iReport generierte Berichte anzeigen soll:

Im Menü Extras-> Optionen wählen Sie im Reiter "iReport"-"Viewers" die entsprechenden Anwendungen:

[[Datei:JasperReports-Handbuch_ireport_viewers.png]]


==== iReport Entwurfsbereich ====

Der Entwurfsbereich bzw. "Designer" hat einen recht komplexen Aufbau. Sie können die Fenster und Seitenbereiche zwar recht flexibel anpassen, aber hier ist die Auslieferung:

[[Datei:JasperReports-Handbuch_designer_ueberblick.png]]

Die wichtigen Bereiche sind hervorgehoben:

* Berichtsstruktur: Welche Seitenbereiche gibt es?
* Datenquelle: Welche Datenbank wird genutzt?
* Abfrage: Was ist die konkrete Abfrage für den Bericht?
* Elemente: Welche Elemente kann ich einfügen, und welche Eigenschaften haben sie?
* Vorschau: wie sieht der Bericht "gedruckt" aus?
* Fehlerausgabe: Jeder Bericht wird "kompiliert", dazu gibt es eine Fehlerausgabe

Im Reiter "Preview" kann man sich eine Vorschau des Ausdrucks anzeigen lassen.


=== Unterschiede iReport und JasperSoft Studio ===

Mit der Version 5.5 wurde die Entwicklung von iReport eingestellt, die Firma JasperSoft empfiehlt seit dem die Benutzung von JasperSoft Studio. Nach unseren Erfahrungen ist die Arbeit mit iReport 4.1.3 (die letzte stabile Version) hier und da "leichtgewichtiger" und einfacher, ganz zu schweigen vom Overhead, den JasperSoft Studio mit Eclipse einbringt. Besonders nervig empfanden wir es, dass JasperSoft Studio anders als iReport verschiedene Objekteigenschaften in Reitern organisiert, und bei jedem Wechsel der Markierung eines Berichtselements muss man in JasperSoft Studio wieder zum richtigen Reiter wechseln.

Andererseits ist JasperSoft Studio kompatibel mit neueren JR-Möglichkeiten. Insbesondere bei dem Umgang mit Diagrammen gibt es in JasperSoft Studio erheblich mehr Möglichkeiten, z.B. Chart Customization. Außerdem ist es vorteilhaft, wenn Sie ohnehin Eclipse nutzen. Sie sollten für Ihre Arbeit also abwägen ob Sie die neueren Möglichkeiten im jeweiligen Bericht überhaupt brauchen, ggf. sind Sie mit iReport besser bedient. Aber das ist Geschmackssache.

<blockquote>Beachten Sie aber bitte: sobald Sie einen Bericht mit JasperSoft bearbeitet und gespeichert haben, ist er mit iReport 4.1.3 nicht mehr bearbeitbar, bzw. nur wenn Sie die [[Berichtsdesign_mit_JasperReports#UUID's|UUIDs]] entfernt haben.
</blockquote>
Beide Produkte befinden sich noch im Einsatz, daher hier nur ein paar Kapitel zur Handhabung der jew. Software.


==== Handhabung ====


===== Preview =====

Bei iReport waren die Buttons für Designer und Preview immer oben.

[[Datei:JasperReports-Handbuch_jss-ir_preview1.png]]

Bei Jaspersoft Studio liegen die Buttons unten:

[[Datei:JasperReports-Handbuch_jss-ir_preview2.png]]


===== Palette =====

Die Palette ist bei iReport und Jaspersoft Studio an gleicher Position zu finden.

Ireport:

[[Datei:JasperReports-Handbuch_jss-ir_palette1.png]]

Jaspersoft Studio:

[[Datei:JasperReports-Handbuch_jss-ir_palette2.png]]


===== Objekt-Eigenschaften =====

Die Objekt-Eigenschaften liegen auch an der gleichen Stelle, jedoch sind bei Jaspersoft Studio die Gruppierungen der Eigenschaften in Karteireiter unterteilt. Bei iReport ist es einfach eine lange Liste mit Unterteilungen.

iReport:

[[Datei:JasperReports-Handbuch_jss-ir_properties2.png]]

Jaspersoft Studio:

[[Datei:JasperReports-Handbuch_jss-ir_properties1.png]]



== JasperReports als Kommandozeilen-Tool ==

In der JasperReports-Distribution befindet sich ein ANT-Script, das mehrere Berichte erzeugen kann.

cd demo/samples

Beispiel xmldatasource:

cd xmldatasource

ant -p

Die Ausgabe ist:

[[Datei:JasperReports-Handbuch_ant_xmldatasource.png]]

Es werden, je nach Auswahl pdf-, Excel- oder andere Berichte erzeugt. Mit dem Target "test" werden alle Targets durchlaufen.

ant test

Achtung: manche Demos brauchen eine laufende HSQLDB (siehe demo/hsqldb).


= Datenquellen =

Allgemein unterstützt JasperReports verschiedene Datenquellen, z.B. relationale Datenbanken, Excel, CSV oder XML. Auch Webservices sind möglich. Speziell für SuperX/ HISinOne-BI gibt es spezielle Datenquellen-Vorgaben, damit Sie die Daten auch im Server-Betrieb nutzen können. Hier also nur die allgemeinen, also SupeRX/BI-unabhängigen Quellen, wenn Sie JasperReports am lokalen Arbeitsplatz nutzen.


== Datenquelle Datenbank ==

Eine relationale Datenbank ist in JasperSoft Studio als "Data Adapter" einzurichten. Oben links befindet sich der Dialog zum Erzeugen (1) des Data Adapter, und dann darunter die Zeile "Database Jdbc Connection" (2):

[[Datei:JasperReports-Handbuch_data_adapter1.png]]

Dort geben Sie dann die jdbc-spezifischen Daten an (Datenbanktyp, Name etc.).

<blockquote>Achtung: die Nutzung setzt eine direkte Datenbankverbindung zum DB-Server voraus, an vielen Unternehmenanwendungen wird dies nicht mehr erlaubt. Ggf. fragen Sie bei Ihren Systemadministrator/innen nach.
</blockquote>


== Datenquelle Excel-Datei ==

Eine Excel Datei ist in JasperSoft Studio als "Data Adapter" einzurichten. Hier ein Beispiel:

[[Datei:JasperReports-Handbuch_datenquelle_excel_1.png]]

Die Excel Datei hat vier Spalten und eine führende Zeile mit den Spaltenüberschriften. Achten Sie darauf, dass die Datentypen der Spalten in Excel dem Inhalt entsprechen. Hier die Spalten:

* Frage Nr.
* Text
* Mit_ohne_schule
* Summe

Aus der Excel-Datei erzeugen Sie einen "Data Adapter". Der Data Adapter vom Typ "Excel File" hat ein paar Eigenschaften:

[[Datei:JasperReports-Handbuch_datenquelle_excel_2.png]]

Danach können Sie in einem Berichtsdesign die Datenquelle definieren:

[[Datei:JasperReports-Handbuch_datenquelle_excel_5.png]]

Sie wählen dort oben links zunächst den "Data Adapter" aus (1), und klicken dann rechts auf "Read Fields" (2):

[[Datei:JasperReports-Handbuch_datenquelle_excel_3.png]]

Aus der Datenquelle werden dann die Datenfelder (3) und Inhalte (Reiter "Data preview") automatisch übernommen.


= Berichtsdesign =

Das Erstellen eines Berichtes erleichtert JasperReports wesentlich. Dennoch wird man sich damit etwas beschäftigen müssen, um ein vernünftiges Ergebnis zu erhalten.

Zuerst muss man den Bericht öffnen. Das geschieht über „Datei“ → „Open“ → Bericht auswählen → auf „Öffnen“ klicken. Nun noch oben links die für diesen Bericht erstellte Datenquelle auswählen und man kann loslegen.

JasperReports bezeichnet die Ausgabebereiche als Bänder. Ein Band ähnelt einer Zeile. Es reicht über die komplette Seitenbreite. Die Höhe kann dabei selbst bestimmt werden und wird dem Informationsgehalt angepasst. Das Band „Detail 1“ ist so etwas wie das Hauptband, in dem dann die Informationen zeilenweise ausgegeben werden. Es wird also eine Schleife über die Daten (Tabelle) ausgeführt und für jeden Datensatz ein mal das Detail Band ausgegeben. Die linke Spalte könnte z.B so aussehen:

[[Datei:JasperReports-Handbuch_iReport-iReport_Leiste_Neu.jpg]]

Hier sieht man, das das Band „Detail 1“ aktiv ist und die anderen wie „Title“ noch nicht. In den Gruppen „Fields“ und „Variablen“ befinden sich die Felder (Spalten) aus der Ergebnistabelle und interessante Variablen wie Seitenzahl, die man nun einfach in das bestehende Band „Detail 1“ per „Drag and Drop“ ziehen kann.

[[Datei:JasperReports-Handbuch_iReport-Feld_Name.jpg]]

Wenn man z.B. in der Gruppe Fields das Feld „Name“ hat und dies in das Band „Detail 1“ zieht,befindet sich ein Platzhalter im Entwurfsbereich:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_1_Namen.jpg]]

Wenn Sie dann auf „Preview“ klicken, wird eine Vorschau des Berichts angezeigt.

[[Datei:JasperReports-Handbuch_iReport-Designer_Preview.jpg]]

Es werden alle Namen aufgelistet, die in der Datenquelle vorhanden sind:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_1_Namen_Ergebnis.jpg]]

Sie können das Layout der Ausgabe (Schriftart, Größe) über die Eigenschaften des Feldes variieren.

Um wieder zurück in den Entwicklermodus zu kommen klickt man einfach wieder auf den Reiter "Designer".

Die Bänder „Title“, „Page“ usw. kann man mit einem Rechtsklick und dann „Add Band“ hinzufügen und auch wieder mit einem rechtsklick und dann „Delete Band“ wieder entfernen. Diese Bänder haben bestimmte Eigenschaften. Z.B. Band „Titel“ wird nur einmal auf der ersten Seite abgebildet, Band „Page Header/Footer“ auf jeder Seite am Anfang/Ende.


== Sortierung und Filtern ==

Normalerweise verarbeitet JasperReports die Datensätze zeilenweise in der Reihenfolge, in der sie bereitgestellt werden. Sie können im Entwurfsmodus die Sortierung bzw. Filterung der Datensätze anpassen:

[[Datei:JasperReports-Handbuch_ireport_sort1.png]]

Klicken Sie auf das Icon mit der Tonne und Sie gelangen in die Einstellungen für die Datenquelle.

[[Datei:JasperReports-Handbuch_ireport_sort2.png]]

Im Button Sortieren können Sie nach allen Feldern des Berichts aufsteigend bzw. absteigend sortieren.

[[Datei:JasperReports-Handbuch_ireport_sort3.png]]

Im Button "Filter expression" können Sie eine Formel definieren, um die Gültigkeit von Datensätzen zu definieren:

[[Datei:JasperReports-Handbuch_ireport_filter1.png]]

Z.B. die Expression ".contains("12") würde auf alle Datensätze filtern, die im Feld die Zeichenkette "12" enthalten. Weitere Infos im Kapitel zum [[#2.9.Expression Editor|outline|Expression Editor]].


== Listen ==

Listen lassen sich einfach erstellen, indem man die jeweiligen Felder ins Detail-Band zieht. Manchmal kann es vorkommen, dass Textfelder "überlaufen", d.h. die rechteckige Box, die das Feld markiert, ist zu klein für den Feldinhalt. Beispiel:

[[Datei:JasperReports-Handbuch_listen_stretch.png]]

In diesem Falle muss man das Attribut des jew. Felder (hier "Fächergruppe") "Text Field properties > Stretch with overflow" ankreuzen.

Achtung: wenn das Feld Teil einer tabellarischen Auflistung ist, muss man die anderen Element mit der Eigenschaft "Stretch type → Relative to tallest object" versehen, hier z.B. die Felder "Studienfeld" und "Studienbereich".

Bei vielen Zeilen ist es übersichtlicher, jede zweite Zeile farbig zu hinterlegen. Dieser Trick ist im Abschnitt Tabellengestaltung [[#2.4.3.Zeilen alternierend einfärben|outline|erläutert]].


== Gruppierung ==

Wichtige Vorbemerkung zum Gruppieren: JasperReports setzt bei der Gruppierung voraus, dass die Datensätze der Datenquelle nach den Gruppierungsmerkmalen sortiert sind. Alle Merkmale, nach denen Sie gruppieren, sollten also entweder direkt in der Datenquelle sortiert sein, oder in JasperReports im [[#2.1.Sortierung und Filtern|outline|Berichtsentwurf]].


=== Gruppen definieren ===

Zu den Standardbändern kann man nun auch noch selbst definierte Gruppen hinzufügen. Mit einem Rechtsklick auf den obersten Knoten → „Add Report Group“ öffnet sich ein Fenster in dem man der Gruppe einen Namen geben kann und das Objekt wählt für das die Gruppe erstellt wird.

[[Datei:JasperReports-Handbuch_designer_add_group.png]]

<blockquote>Achtung: wenn Sie mehrere Gruppierungsebenen benötigen, dann sollte die Reihenfolge des Hinzufügens der Gruppen "top-down" verlaufen, d.h. zuerst die oberste Gruppierung hinzufügen, dann die Gruppe darunter usw.
</blockquote>
In dem folgenden Beispiel wird die Gruppe „Monat“ gewählt und in dem nächsten Schritt mit Header und Footer hinzugefügt:

Man zieht das Feld „Namen“ in das Band „Detail“ und „Monat“ in das erstellte Band „Monat Group Header 1“. Aus der Palette rechts oben (wenn nicht vorhanden bekommt man es über „Fenster“ → „Palette“) zieht man einen „Static Text“ in das Band „Monat Group Header 1“ vor der Ausgabe des Monats, benennt das Feld „Monat:“ und noch eine Linie darunter. Zusammen sollte es so aussehen:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_Monat_Namen.jpg]]

Wenn man nun auf „Preview“ klickt erhält man als Ergebnis:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_Monat_Namen_Ergebnis.jpg]]


=== Seitenumbrüche ===

Damit eine Gruppe nicht durch einen Seitenumbruch auseinandergerissen wird, gibt es einige Einstellungen in dem Band der Gruppe. Dazu einfach auf das jeweilige Band klicken, für welches die Einstellungen vorgenommen werden sollen und dann in „Eigenschaften“ → „Group properties“ → „Keep Together“ anklicken oder wenn man möchte „Reprint header“ um den "Header" der Gruppe am Seitenkopf zu wiederholen.

Sie können auch angeben daß vor jedem Gruppierungswechsel ein Seitenumbruch ausgeführt wird:

[[Datei:JasperReports-Handbuch_designer_add_group_new_page.png]]

Mit "Start on a new page" wird eine neue Seite bei jedem Gruppenwechsel begonnen. Speziell beim Export nach Excel kann dies in Tandem mit Arbeitsblättern nutzen, siehe [[#2.19.2.Excel-Export in einzelne Tabellenblätter|outline|unten]].


=== Gruppensummen ===

Gruppensummen kann man im Kopf oder Fuß einer Gruppe anlegen. Sie aktivieren z.B. den Gruppenfuß im Report Inspector, und ziehen dann das Feld Summe in den Entwurfsbereich. Beim "Fallenlassen" werden Sie gefragt, ob Sie den jew. Wert oder eine Aggregatfunktion nutzen wollen. Für Zwischensummen wählen Sie "Sum":

[[Datei:JasperReports-Handbuch_designer_add_group_foot1.png]]

Im Entwurfsbereich setzen Sie noch ein Label bzw. "Static Text"-Element rechtsbündig davor, und setzen beide Elemente fett:

[[Datei:JasperReports-Handbuch_designer_add_group_foot2.png]]


=== Gruppierung ohne eigenes Band ===

Bei der Gruppierung in JasperReports wird in der Regel ein horizontales Band für die Gruppierungsebene angelegt. Das führt dazu, daß man zeilenorientiert gruppiert. In manchen Fällen kann es gewünscht sein, in den Spalten einer Tabelle zu gruppieren. Hier ein Beispiel für das Ziel:

[[Datei:JasperReports-Handbuch_gruppierung_spalten1_vorlage.png]]

In dem Beispiel wird in den Zeilen nach dem Merkmal '''Fach''' gruppiert. Zusätzlich wird noch in den Spalten nach Fachsemestern gruppiert. Um dieses Layout zu realisieren, muss man wie folgt vorgehen:

Erzeugen Sie ein Column Header Band, und ein Group Footer-Band für die Gruppierungsebene Fach. Warum Group Footer? Weil innerhalb des Fachs nochmal gruppiert werden soll, und daher erst nach dem Gruppieren nach Fach nach Fachsemestern gruppiert wird. Ein Detail-Band gibt es hier nicht.

[[Datei:JasperReports-Handbuch_gruppierung_spalten3_band.png]]

Erzeugen Sie eine neue Variable z.B. mit dem Namen "fs1" für erstes Fachsemester, und geben Sie der Variable folgende Eigenschaften:

[[Datei:JasperReports-Handbuch_gruppierung_spalten2_variable_1fs.png]]

Zur Erläuterung: Die Variable filtert die Datensätze gemäß dem Ausdruck in Variable Expression, und tut dies auf der Gruppierungsebene "fach". Die Variable Expression ist eine für unsere Zwecke sehr nützliche Java-Kurzfassung einer IF-THEN-Bedingung, und meint:

<blockquote>Wenn der Inhalt des Feldes "Anzahl Fachsemester" gleich 1 ist, dann gib die Summe der jew. Studierenden aus, wenn nicht, dann gib 0 aus.
</blockquote>
Analog kann man noch die Variable "fsgr13" für "Fachsemester > 13" anlegen.

Danach kann man die Variablen "fs1" und "fsgr13" in das Band "Fach Group Footer 1" ziehen, und noch das Feld "Summe" für die Gesamtsumme. Dann tragen wir im Column Header Band noch die Spaltenüberschriften ein. Insgesamt sieht Berichtsentwurf dann so aus:

[[Datei:JasperReports-Handbuch_gruppierung_spalten4_band.png]]

Und das Ergebnis sieht so aus:

[[Datei:JasperReports-Handbuch_gruppierung_spalten5_band.png]]

Fertig. Man könnte nun noch weitere Fachsemester-Intervalle einfügen, oder z.B. eine Summe der Studierenden in der Regelstudienzeit.


=== Gruppierung mit virtuellen Dimensionen ===

Wenn Sie nach Feldern gruppieren wollen, die es in Ihrer Datenquelle gar nicht gibt (z.B. nach Aggregationen von Mekrmalskombinationen), dann können Sie auch Variablen mit speziellen Formeln anlegen, und diese dann in die Gruppierung aufnehmen.

<blockquote>Wichtig: Wenn die Gruppierungsvariable nicht im Summary Band genutzt wird, muss der resettype der Variable auf „None“ gesetzt werden.
</blockquote>
Im Abschnitt zu [[#2.5.4.Kreuztabellen mit virtuellen Dimensionen|outline|Kreuztabellen]] wird z.B. gezeigt, wie die Fächer Mathe, Physik und Biologie in einen neuen Wert "Naturwissenschaften" transformiert werden.


=== Variablen und Gruppierung ===

Beim Anlegen von Gruppen-Bändern und beim Ziehen von Feldern in das jew. Gruppenband legt JR automatisch eine Variable an, mit der jew. Aggregationsfunktion. Diese Variable hat folgende Eigenschaften:

Expression: das Feld, aus dem die Variable gespeist wird

Calculation: Die Aggregatfunktion, z.B. "sum"

Reset Type: Die Gruppierungsebene

Wenn Sie die Variable in Textfeldern des Gruppenbandes nutzen, gibt sie jeweils den richtigen Wert an, egal ob Gruppenkopf oder Fuß.

Wenn Sie aber mit "Print-when-Expressions" im Gruppenband arbeiten und auf die Variablen zugreifen, funktionieren diese standardmäßig nur im Gruppenfuß, weil erst am Ende der Gruppe der Wert bekannt ist. In diesem Fall müssen Sie der Variable auch eine "Initial Value Expression" mit dem jew. Feld geben.


=== Berechnungen auf Gruppenebene ===

Wenn Sie auf der Gruppenebene Berechnungen, z.B. Mittelwerte, durchführen wollen, gibt es einige Fallstricke:

* Die in JR eingebauten Funktionen wie "avg" arbeiten auf Gruppenebene nicht immer exakt.
* Komplexere Formeln auf Gruppenebene in Variablen abzubilden und diese dann das Quelle für Textfelder zu nehmen hat bei uns nicht geklappt.

Hier unser Vorgehen:

* Definieren Sie auf der Ebene der jew. Gruppe eine Variable mit der Gesamtsumme, und eine mit der Summe der zu mittelnden Werte. Diese Variablen haben als "reset Type" die jew. Gruppierungsebene.
* Im Textfeld, das Sie ausgeben, verwenden Sie dann die Berechnungsformel, z.B. einen Quotienten. Verwenden Sie für die Berechnung nicht eine neue Variable, sondern fügen Sie die Formel direkt in das Textfeld ein.

Im folgenden ein Beispiel: Wir haben eine Absolventenliste pro Studiengang und Semester, darin werden dann Mittelwerte von Abschlussnoten gebildet. Die Datenquelle hat summierte Zeilen pro Note:

[[Datei:JasperReports-Handbuch_notenschnitt_daten.png]]

Im obigen Beispiel haben wir in der Zeile 5 eine Absolventin mit der Note 1,1. In der letzten Zeile haben wir zwei Absolventinnen mit der Note 1,2.

Würden wir den Notenschnitt manuell berechnen, müßten wir die Notensumme (Spalte H*K) ermitteln, hier wäre der Wert 32,3. Die Summe der Absolventen in Spalte K wäre 16, d.h. der Notenschnitt wäre 32,3/16 = 2,02.

In JasperReports wäre der Entwurf wie folgt:

[[Datei:JasperReports-Handbuch_notenschnitt_design1.png]]

Wir haben eine Variable "Summe_1" auf der Ebene des Semester-Bandes, die im obigen Excel der Summe der Spalte "Summe" entspricht.

Außerdem haben wir eine Variable "Notensumme" mit der Formel $F{Note}*$F{Summe}, auf der Ebene der Gruppe "Semester". Achten Sie drauf, dass Sie als Typ "java.lang.Double" nehmen, damit Sie keine Rundungsfehler bekommen.

Der Quotient wird dann im Textfeld gebildet, das den Notenschnitt auf Semesterebene enthält, und auf zwei Nachkommastellen gerundet:

[[Datei:JasperReports-Handbuch_notenschnitt_design2.png]]

Das Textfeld selbst muss bei "Evaluation time" den Wert "Group" haben, und bei "Evaluation group" dann den Wert der Gruppe "Semester". Und hier das Ergebnis in der Vorschau:

[[Datei:JasperReports-Handbuch_notenschnitt_vorschau.png]]

Der Wert 2,02 stimmt mit unserer manuellen Berechnung überein.


== Tabellengestaltung ==


=== Summen, Seitenzahlen ===

Um es noch ein wenig interessanter zu gestalten fügt man noch das Gehalt hinzu, summiert es für die Monate und gesamt. Dazu noch die Seitenanzahl und einen Seitenzähler und eine Überschrift.

Das Gehalt bekommt man, indem man das Gehalt aus den Feldern neben den Namen zieht. Das selbe macht man auch nochmal in das Band „Monat Group Footer 1“ und wählt hier die Aggregation „Sum“ aus, um die Summe zu erhalten.

Um einen Seitenzähler zu erhalten fügt man zunächst das Band „Page Footer“ hinzu und legt dort die Variable „PAGE_NUMBER“ ab.

[[Datei:JasperReports-Handbuch_iReport-Page_Number.jpg]]

Unter „Eigenschaften“ → „Text field properties“ → „Evaluation Time“ wählt man hier „Now“ um die aktuelle Seitenanzahl zu bekommen und „Report“ um die gesamte Seitenanzahl zu erhalten. In dem Beispiel ist die Ausgabe z.B.: „Seite 2 von 6“.


=== Seitenumbrüche steuern ===

Damit die drei Personen im Monat 2 nicht durch einen Seitenumbruch auseinandergerissen werden, gibt es einige Einstellungen in dem Band der Gruppe. Dazu einfach auf das jeweilige Band klicken, für welches die Einstellungen vorgenommen werden sollen (hier „Monat“) und dann in „Eigenschaften“ → „Group properties“ → „Keep Together“ anklicken oder wenn man möchte „Reprint header“ um den "Header" der Gruppe am Seitenkopf zu wiederholen.

Beispiel im Designermodus:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_2_Monat_Namen.jpg]]

Beispiel im Preview:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_2_1_Monat_Namen_Ergebnis.jpg]]

[[Datei:JasperReports-Handbuch_iReport-Beispiel_2_2_Monat_Namen_Ergebnis.jpg]]


=== Zeilen alternierend einfärben ===

Um nun bei mehreren Datensätzen auch noch den Überblick in den Zeilen zu behalten kann man jetzt auch noch den Hintergrund der Zeile abwechselnd farbig gestalten. Dazu Zieht man aus den „Reports Elements“ das „Rectangle“ in das „Detail 1“ Band

[[Datei:JasperReports-Handbuch_iReport-Even_Odd_2.jpg]]

und passt es der Größe des Bandes an.

[[Datei:JasperReports-Handbuch_iReport-Even_Odd_1.jpg]]

Die Hintergrundfarbe kann man nun in den Eigenschaften in „Backcolor“ ändern. Damit dies nun nicht in jeder Zeile erscheint, sondern abwechselnd, fügt man noch in den Eigenschaften in „Print When Expression“ den Wert Boolean.valueOf( $V{PAGE_COUNT}.intValue() % 2 == 0 ) ein.

Zur erläuterung:

Die Variable „PAGE_COUNT“ zählt die Anzahl der Datensätze hoch. Mit „% 2“ wird diese Variable durch 2 geteilt und nur der Restwert ausgegeben. Als Ergebnis erhält man also in jeder ungeraden Zeile eine 1. Dieses Ergebnis wird nun mit der „0“ verglichen. Wenn dieser Ausdruck/Vergleich (expression) wahr ist, wird das Objekt, in diesem Fall der Hintergrund, angezeigt. Bei diesem Ausdruck erhält also jede gerade Zeile den Hintergrund. Möchte man lieber die ungeraden Zeilen hervorheben, schreibt man einfach eine 1 anstelle der 0 hinter „==“.

[[Datei:JasperReports-Handbuch_iReport-Even_Odd_3.jpg]]

Das Ergebnis bei einer ungeraden Hervorhebung sieht z.B. so aus:

[[Datei:JasperReports-Handbuch_iReport-Even_Odd_4.jpg]]

Ein weiteres Beispiel welches bereits in der Uni Mannheim benutzt wird ist die Ausgabe einer Rechnungslegungsliste. Das Beispiel zeigt nicht nur ein aufwändigeres Layout, sondern auch, wie man gruppierte Tabellen anlegt: Dabei sind die Zeilen der Tabelle im Detail 1 Band, und die Zwischensummen in den Gruppierungs-Bändern. Die Spaltenüberschriften der Tabelle befinden sich im untersten Group-Header-Band. Im Designermodus sieht das ganze folgendermaßen aus:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_3_Uma.jpg]]

Und im Preview:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_3_Uma_Ergebnis_1.jpg]]

[[Datei:JasperReports-Handbuch_iReport-Beispiel_3_Uma_Ergebnis_2.jpg]]


=== Rahmenlinien '''vorausschauend setzen''' ===

Sowohl bei Text- als auch bei Static-Fields findet sich ein eigener Reiter zum setzen von Rahmeneigenschaften. Dort wird der Abstand des Inhaltes zum Rahmen des jeweiligen Feldes definiert, sowie Rahmenlinien gesetzt.

Beim Setzen von Rahmenlinien wird empfohlen, dass bei nebeneinanderliegenden Feldern, welche durch eine Rahmenlinie getrennt werden, jeweils in beiden Feldern Rahmenlinien gesetzt werden und nicht nur in einem der beiden Felder. Denn beim Export in das PDF-Format ist ersichtlich ob nur eines der Felder oder beide Felder Rahmenlinien besitzen. Falls dies also nicht einheitlich umgesetzt wird, erscheinen Rahmenlinien an entsprechenden Stellen dünner beziehungsweise dicker (bei Excel-Dokumenten tritt dieser Effekt nicht auf):

[[Datei:JasperReports-Handbuch_borders2.png]]


== Unterberichte ==

<blockquote>Achtung: In Edustore funktionieren Unterberichte nur, wenn der Dateiname der jrxml-Datei mit "_xmlsource.jrxml" endet. Dadurch wird dem Servlet mitgeteilt, dass die Datenquelle für den Bericht ein XML-Datenstrom ist. Dabei ist mit Performanceeinbußen zu rechnen. 
Außerdem muss beim Berichtsdesign die gleiche JasperReports Version genutzt werden wie im Server.
</blockquote>
Im folgenden eine Anleitung zur Erstellung eines Unterberichts:


=== Konfiguration des Hauptberichts ===

Erzeugen Sie für den Unterbericht mit Hilfe des [[#2.1.3.Template erzeugen|outline|Template]][[#2.1.3.Template erzeugen|outline|-Generators]] in Edustore einen leeren Bericht, und speichern Sie diesen am besten im gleichen Verzeichnis wie den Hauptbericht.

Ziehen Sie dann das Subreport-Werkzeug in den Entwurfsbereich:

Ggf.

[[Datei:JasperReports-Handbuch_subreport0_tool.png]]

Es startet der Subreport-Assistent. Hier geben Sie zunächst den Dateinamen oben an:

[[Datei:JasperReports-Handbuch_subreport1_wizard1.png]]

Im nächsten Schritt geben Sie eine Datenbank-Verbindung an. Hier wählen Sie "Don't use any connection...":

[[Datei:JasperReports-Handbuch_subreport1_wizard2.png]]

Im nächsten Schritt werden Parameter angezeigt, zu diesem Zeitpunkt gibt es aber noch keine.

[[Datei:JasperReports-Handbuch_subreport1_wizard3.png]]

Klicken Sie einfach auf "Weiter". Sie werden dann aufgefordert, einen Dateipfad für den Unterbericht zu vergeben. IReport legt diesen standardmäßig in das gleiche Verzeichnis wie den Hauptbericht. Für Edustore sollten Sie dies auch tun.

Bitte beachten Sie dass Sie beim Unterbericht nicht die *.jrxml-Datei verlinken, sondern die *.jasper-Datei, d.h. den kompilierten Report.

[[Datei:JasperReports-Handbuch_subreport1_wizard4.png]]

Danach sehen Sie einen Platzhalter für den Unterbericht im Entwurfsbereich. Beachten Sie bitte daß die Größe des Platzhalters unwichtig ist: die Ausdehnung des Unterberichts wird im Unterbericht definiert. Der Platzhalter ist lediglich wichtig, um die linke obere Ecke des Unterberichts festzulegen. 
Rechts neben dem Platzhalter sehen Sie die Eigenschaften des Unterberichts:

[[Datei:JasperReports-Handbuch_subreport2_params_none.png]]

Ein Unterbericht arbeitet meist mit Übergabe von Parametern, z.B. will man vom Hauptbericht den Inhalts des Feldes "Kostenstelle" an den Unterbericht übergeben. Dies müssen wir in den Eigenschaften des Unterberichts "deklarieren". In der Zeile "Parameters" steht nach Bedienung des Assistenten noch kein Wert. Für die Datenquelle XML gibt es außerdem einen Parameter XML_DATA_DOCUMENT, der immer übergeben werden muss: Die XML-Datenquelle des Hauptberichts. Hier eine Übersicht, welche Parameter übergeben werden:

[[Datei:JasperReports-Handbuch_subreport10_parameters.png]]

Die Zeilen mit Großschreibung sind die vorgegebenen Werte, der Parameter "Kst" speist sich aus dem JR-Feld "Kostenstelle". Das Beispiel zeigt, daß der Name für den Parameter beliebig ist.

'''Hinweis für Unterberichte mit Dezimalzahlen''': Wenn der Unterbericht mit Zahlen mit Nachkommastellen arbeitet, und Sie in JasperReports testen, dann müssen Sie noch die [[#3.1.2.Datenquelle erzeugen|outline|Parameter]] XML_LOCALE und XML_NUMBER_PATTERN wie folgt übergeben:

[[Datei:JasperReports-Handbuch_subreport2_params_number.png]]


=== Unterbericht mit Header und Footer vom Hauptbericht ===

Wenn der Unterbericht in einem normalen Gruppen- oder Detail-Band liegt, wird der Header und Footer vom Hauptbericht automatisch mitbenutzt. In vielen Fällen möchte man aber den Unterbericht nur ein mal ausgeben und legt ihn daher in das Summery-Band. Hier wird Standardmäßig der Header und Footer nicht ausgegeben oder wiederholt. Möchte man aber z.B. die Seitenzahl die im Footer liegt weiterhin angezeigt bekommen, gibt es eine Eigenschaft vom Hauptbericht, die man nur aktivieren braucht. Diese Eingenschaft nennt sich: Summary with Page Header and Footer.

Also einfach auf den Hauptbericht auswählen und in Eigenschaften diesen Punkt aktivieren.

[[Datei:JasperReports-Handbuch_subreport_header_footer.png]]


=== Konfiguration des Unterberichts ===

Nun können wir den Unterbericht öffnen, indem wir über dem Platzhalter die rechte Maustaste betätigen und "Open Subreport" wählen.

[[Datei:JasperReports-Handbuch_subreport3_open.png]]

Es erscheint ein neues Fenster mit einem leeren Entwurfsbereich. Sie könnten nun loslegen und im Detailbereich verschiedene Elemente gestaltet. Aber man muss bedenken daß ein Unterbericht für jeden Datensatz im Hauptbericht ausgeführt und eingebettet wird. Daher wird man vermutlich in den meisten Fällen im Unterbericht auf einen Filter zurückgreifen. Hier kommt dann wieder der oben genannte Parameter, z.B. "Kst" ins Spiel: Als ersten deklarieren wir den Parameter im Unterbericht, indem wir Links bei den Parametern die rechte Maustaste drücken, und "Hinzufügen..." wählen:

[[Datei:JasperReports-Handbuch_subreport4_param.png]]

Standardmäßig nennt IReport den Parameter "parameter1". Rechts können wir in den Eigenschaften des Parameters den Namen ändern, und "Use as a prompt" abwählen:

[[Datei:JasperReports-Handbuch_subreport4_param2.png]]

Weitere Änderungen sind nicht notwendig.

Wir ergänzen nun die "Report Query" [[Datei:JasperReports-Handbuch_report_query.png]] des Unterberichts von

''/ergebnisse/ergebnis/ergebniselement/sqlerg/row''

um einen Filter, der mit der Abfragesprache XPATH formuliert wird. Im obigen Beispiel würden wir jetzt nur die Zeilen der Datenquelle auswählen, wo die Nummer der Kostenstelle mit der des Hauptberichts übereinstimmt. Wir erinnern uns: letztere steht im Parameter "Kst". Anhand der vorhandenen Report Query können wir sehen, dass die Kostenstelle in den Spalten ("col") mit der id=5 steht. Der Ausdruck wird also um den Filter "''[col[@id="5"]/wert='''''$P{Kst}']''" ergänzt:

[[Datei:JasperReports-Handbuch_subreport4_query.png]]

Nun ändern wir im Entwurfsbereich des Unterberichts das Layout: für das aktuelle Beispiel wollen wir im Unterbericht eine Summe der Beträge für jede Kostenstelle ausgeben. Dazu müssen wir zunächst eine Gruppierung nach Kostenstelle hinzufügen:

[[Datei:JasperReports-Handbuch_subreport5_group1.png]]

Im Gruppierungsassistenten wählen wir das Feld "Kostenstelle" als Gruppierungsmerkmal, und im nächsten Schritt sagen wir, daß ein Gruppenkopf hinzugefügt werden soll:

[[Datei:JasperReports-Handbuch_subreport5_group2.png]]

Danach ist die Gruppierung als Band verfügbar:

[[Datei:JasperReports-Handbuch_subreport5_group3.png]]

In die Gruppierung ziehen wir dann das Feld "Summe":

[[Datei:JasperReports-Handbuch_subreport5_group4.png]]

Beim "Loslassen" des Feldes werden wir gefragt, ob wir eine Aggregatfunktion nutzen wollen; wir wählen hier die Summierung:

[[Datei:JasperReports-Handbuch_subreport5_group5.png]]

Danach ist das Feld verfügbar. Wir setzen noch das Label "Summe:" davor.

[[Datei:JasperReports-Handbuch_subreport5_group6.png]]

Den Detailbereich brauchen wir eigentlich nicht, wir können den ganz schmal machen. Danach speichern wir den Unterbericht, und gehen wieder zum Hauptbericht. Hier setzen wir den Unterbericht direkt unter das Feld "Kostenstelle":

[[Datei:JasperReports-Handbuch_subreport15_align.png]]

Danach können wir den Bericht mit der jew. Datenquelle ausführen. Das Ergebnis läßt je nach Datenmenge ein bisschen auf sich warten:

[[Datei:JasperReports-Handbuch_subreport20_erg.png]]


=== Einhängen des Berichts in Edustore ===

Damit der Bericht auch im Server nutzbar ist, muss noch folgendes eingestellt werden:

* Der Server sollte ausreichend RAM haben (Variable CATALINA_OPTS), weil hier XML als Datenquelle verarbeitet wird.
* Im Hauptbericht gibt es einen neuen Parameter SUBREPORT_DIR. Setzen Sie hier den Defaultwert ("Default value Expression" auf den Pfad, in dem die Dateien liegen (z.B. "/home/superx/webserver/tomcat/webapps/superx/WEB-INF/reports/").
* Kopieren Sie die .jasper Datei des Unterberichts in dieses Verzeichnis.
* Bei Nutzung von Versionskontrollsystemen haben Sie die *.jasper-Dateien vermutlich ignoriert (gitignore / svnignore). Sie müssen die Dateien daher mit "-f" adden / committen.

<blockquote>Vorsicht beim Einsatz von JasperSoft Studio: Die Anwendung erzeugt bei der Einzelbearbeitung eines Unterberichts nicht automatisch eine entsprechende .jasper-Datei beim Previewen des Hauptberichts (iReport machte das). Man muss also in Jaspersoft Studio im Bearbeitungsfenster oben immer "Compile Report" anklicken, um eine neue .jasper Datei zu erzeugen.
</blockquote>

== Kreuztabellen ==


=== Bedienung des Assistenten für Kreuztabellen ===

Für die Erstellung von Kreuztabellen gibt es einen eigenen Assistenten. Vorab sollte man aber zunächst ein "Summary"-Band erzeugen. Im folgenden Beispiel haben wir alle anderen Gruppierungen und Detail-Bands entfernt:

[[Datei:JasperReports-Handbuch_designer_crosstab1.png]]

Dann ziehen wir das Crosstab-Element in den Summary Band. Es erscheint der Assistent. Als Datenquelle nutzen wir die Abfrage des Berichts.

[[Datei:JasperReports-Handbuch_designer_crosstab2.png]]

Als nächsten definieren wir die Zeilendimension des Berichts:

[[Datei:JasperReports-Handbuch_designer_crosstab3.png]]

Wir wählen z.B. die Abschlüsse. Danach definieren wir die Spalten-Dimension:

[[Datei:JasperReports-Handbuch_designer_crosstab4.png]]

Wir wählen das Merkmal "Geschlecht". Danach definieren wir das Merkmal, das in den Zellen ausgegeben werden soll. Dies ist die Summe der Studierenden:

[[Datei:JasperReports-Handbuch_designer_crosstab5.png]]

Zum Schluß kann man ein Layout festlegen, und Zeilen- und Spaltensummen erzeugen:

[[Datei:JasperReports-Handbuch_designer_crosstab6.png]]

Im Entwurfsbereich erscheint ein neues Fenster mit der Kreuztabelle.

[[Datei:JasperReports-Handbuch_designer_crosstab7.png]]

Hier können wir nun Spaltenbreiten und Überschriften ändern:

[[Datei:JasperReports-Handbuch_designer_crosstab9.png]]

Das Ergebnis sieht wie folgt aus:

[[Datei:JasperReports-Handbuch_designer_crosstab8.png]]


=== Nachbearbeitung des Kreuztabellen-Assistenten ===

Der Assistent liefert nur einfache Kreuztabellen, ggf. wollen Sie diese im Nachhinein anpassen. Sie können z.B. mehr als zweistufige Hierarchien in Kreuztabellen einrichten, indem Sie im Report Inspector manuell neue Merkmale anlegen.

[[Datei:JasperReports-Handbuch_crosstab_new_row.png]]

Auch bei "Measures" können Sie neue "abhängige Variablen" anlegen, z.B. wenn Sie in einer Tabelle mit den Zeilen "Ausgaben" und "Einnahmen" die Ausgaben mit negativem Vorzeichen versehen wollen und dann saldieren wollen: Sie würden ein neues "Measure" anlegen, mit der Calculation="Sum", Typ "java.lang.Float", und der folgenden Expression bekommen alle Ausgaben ein negat. Vorzeichen:

($F{Kostenart}=="Ausgaben")?-$F{Betrag}:$F{Betrag}

Das neue Measure können Sie dann in die Zeilen- oder Spaltensummen ziehen.


=== Kreuztabellen im Gruppenfuß ===

Kreuztabellen lassen sich nicht nur im Summary Band nutzen, sondern auch in Gruppenfuß/Gruppenkopf-Bändern. Wenn Sie die Kreuztabelle z.B. in einen Groupfooter legen, müssen Sie den "Reset type“ der Gruppe anpassen. Das machen Sie indem Sie ein rechts klick auf die Kreuztabelle machen und dann auf "Crosstab data" klicken. Dort stellen Sie den "Reset type" auf "Group" und die "Reset group" auf die Gruppe in der die Kreuztabelle gelegt wurde. Wenn Sie das nicht machen funktioniert der Report nicht!


=== Kreuztabellen mit virtuellen Dimensionen ===

Sie können auch virtuelle Dimensionen in Kreuztabellen nutzen, indem Sie ähnlich wie bei der [[#2.2.4.Gruppierung ohne eigenes Band|outline|Gruppierung ohne eigenes Band]] mit Variablen arbeiten.

Um z.B. alle Studienfächer im Feld "1. Fach" auszugeben, und nur die Fächer Mathematik, Physik und Biologie zu einem Fach "Naturwissenschaften" zusammenzufassen, legen Sie eine neue Variable "fachgruppe" an, mit der Expression:

[[Datei:JasperReports-Handbuch_gruppierung_virtuell.png]]

In der Kreuztabelle können Sie nun z.B. in den Zeilen die Variable "fachgruppe" auswählen, und erhalten eine Tabelle mit der "künstlichen" Zeile "Naturwissenschaften":

[[Datei:JasperReports-Handbuch_gruppierung_virtuell2.png]]


=== Sortierung in Kreuztabellen ===

Zeilen- oder Spaltendimensionen werden in Kreuztabellen immer alphabetisch sortiert, egal wie die Sortierung in der Datenquelle ist. Das ist in der Regel kein Problem, aber wenn z.B. eine Zeilendimension anders sortiert werden soll, geht das nicht ohne weiteres. Hier ein Problembeispiel:

[[Datei:JasperReports-Handbuch_kreuztab_sortierung_falsch.png]]

Das Balkendiagramm übernimmt die Sortierung nach dem Schlüssel der Gehaltsgruppe aus der Datenquelle. In der Kreuztabelle wird die Zeilendimension "Bezeichnung der Gehaltsgruppe" angezeigt, und diese sortiert alphabetisch, was an dieser Stelle aber unsinnig ist: Der Eintrag "Kein Einkommen" sollte ganz oben stehen.

Wir schauen uns zunächst die Definition der Kreuztabelle an:

[[Datei:JasperReports-Handbuch_kreuztab_sortierung_richtig1.png]]

Die Zeilendimension sortiert aufsteigend nach Bezeichnungstext. Man kann auch keine alternative Expression als Sortierkriterium angeben. Wir müssen also einen Trick anwenden: wir nehmen den Sortierschlüssel mit in die "Bucket Expression" der Zeilendimension auf, und setzen ihn als Präfix davor:

[[Datei:JasperReports-Handbuch_kreuztab_sortierung_richtig2.png]]

Danach ist die Sortierung richtig:

[[Datei:JasperReports-Handbuch_kreuztab_sortierung_richtig3.png]]

Aber optisch ist das natürlich unschön, der Sortierschlüssel sollte am besten gar nicht angezeigt werden. Wir lösen das, indem wir den Anzeigetext wiederum so abwandeln, dass der erste Buchstabe nicht sichtbar ist. Java bietet dazu die Funktion "substring()":

[[Datei:JasperReports-Handbuch_kreuztab_sortierung_richtig4.png]]

Und siehe da: die Sortierung und Anzeige ist perfekt:

[[Datei:JasperReports-Handbuch_kreuztab_sortierung_richtig5.png]]

Dies ist nur ein Beispiel, wie man mit Hilfe von Java Expressions die Anzeige von Kreuztabellen variieren kann.


=== Parameter für Kreuztabellen ===

In Kreuztabellen hat man keinen direkten Zugriff auf die Variablen und Felder des Hauptberichts. Man kann die Werte aber als Parameter übergeben. Dazu gehen Sie wie folgt vor:

Sie machen den Parameter im Crosstab-Element bekannt, hier z.B. der Parameter "RSZ" für Regelstudienzeit):

[[Datei:JasperReports-Handbuch_crosstab_param1.png]]

Danach übergeben Sie den Parameter im Hauptbericht. Mit Rechtsklick auf das Cosstab Element können Sie eine Parameters-Map Expression hinterlegen, das ist einfach eine Zuweisung von einer oder mehreren Variablen zu jeweils einem Wert in der Groovy-Syntax mit "[Variable:Wert,...]". In dem Beispiel unten weisen wir dem Parameter "RSZ" den Wert des Feldes "RSZ" zu:

[[Datei:JasperReports-Handbuch_crosstab_param2.png]]

Danach können wir den Parameter in der Kreuztabelle nutzen, z.B. um in einer Spaltenüberschrift nur dann eine Zahl mit Soll-Kreditpunkten anzuzeigen, wenn die Fachsemester innerhalb der Regelstudienzeit liegen.

[[Datei:JasperReports-Handbuch_crosstab_param3.png]]

Und hier das Ergebnis für einen Studiengang mit 6 Semestern Regelstudienzeit:

[[Datei:JasperReports-Handbuch_crosstab_param5.png]]


=== Manuelle Kreuztabelle ===

Wenn die gewünschte Konfiguration/Einstellungen in der Kreuztabelle nicht möglich ist, kann eine Kreuztabelle mit Einschränkungen auch selber erstellt werden. Im Beispiel mit Semestern, muss vorher abgeschätzt werden wie viele Semester vorraussichtlich in den Spalten vorkommen werden. Für jedes Semester (z.B. für 10 Semester) wird dann eine Variable angelegt. Die erste bekommt das höchste Semester (wie im Screenshot zu sehen).

[[Datei:JasperReports-Handbuch_kreuztabelle_manuell_1.jpg]]

Das zweite Semester wir dann das höchste welches aber unterhalb von dem ersten liegen soll, usw.

[[Datei:JasperReports-Handbuch_kreuztabelle_manuell_2.jpg]]

Diese Semester können nun als Spalten verwendet werden mit der Option „blank when null“.


=== Layout von Kreuztabellen bearbeiten ===

Dieser Abschnitt befasst sich mit Themen zur Layoutanpassung.


==== Total einer ‚Row Group‘ entfernen ====

Wenn eine neue ‚Row Group‘ angelegt wird, wird automatisch ein dazugehöriges Total-Feld erzeugt und mit eingefügt:

[[Datei:JasperReports-Handbuch_Eingebettet_001.png|642x367px]]

Das ist in diesem Falle nicht erwünscht. Um dieses Feld zu entfernen, wird in den Properties der ‚Row Group‘ die ‚Total Position‘ = ‚none’ gesetzt:

[[Datei:JasperReports-Handbuch_Eingebettet_002.png|642x263px]]


==== Header von ‚Row Groups‘ für jede Zeile wiederholen ====

Im folgenden Screenshot ist eine Kreuztabelle dargestellt, bei welcher die Header der ‚Row Groups‘ nur einmal dargestellt werden:

[[Datei:JasperReports-Handbuch_Eingebettet_003.png|434x315px]]

Zwar ließe sich das Feld noch, so dass es bis zum nächsten ‚Row Header‘ reicht, aber in diesem Beispiel ist erwünscht, dass sich der Header für jede Zeile wiederholt:

[[Datei:JasperReports-Handbuch_Eingebettet_004.png|530x420px]]

Dazu wird die Funktion ‚Merge Header Cells‘ in den Properties der ‚Row Group‘ deaktiviert. Es kann sein, dass die Funktion einmal aktiviert und dann wieder deaktiviert werden muss, damit sie als deaktiviert erkannt wird.

[[Datei:JasperReports-Handbuch_Eingebettet_005.png|642x275px]]

Damit der Text in der ersten Spalte nicht abgeschnitten wird, wurde ‚Stretch with Overflow‘ in den Text-Field-Properties ausgewählt. Dadurch ist eine Lücke bei den anderen Spalten entstanden.

[[Datei:JasperReports-Handbuch_Eingebettet_006.png|509x404px]]

Um diese Lücke zu schließen wird der ‚Stretch Type‘ in allen folgend eingerahmten Textfeldern auf ‚Relative To Band Height (deprecated)‘ gesetzt:

[[Datei:JasperReports-Handbuch_Eingebettet_007.png|642x322px]]


==== ‚Static Field‘ und ‚Text Field‘ frei gestalten/bewegen ====

Im Default sind ‚Static Field‘ und ‚Text Field‘ in einer Kreuztabelle nicht frei positionierbar/gestaltbar. Um das zu ändern, wird im jeweiligen Bereich das Layout auf ‚Free Layout‘ eingestellt.

[[Datei:JasperReports-Handbuch_Eingebettet_008.png|642x279px]]


==== Reihenfolge der ‚Row Groups‘ ändern ====

Die Reihenfolge der ‚Row Groups‘ muss nachträglich im ‚Outline‘-Bereich geändert werden. Dies erfolgt per Drag and Drop im rot markierten Bereich:

[[Datei:JasperReports-Handbuch_Eingebettet_009.png|642x437px]]

Die Textfelder im Design-Bereich zu verschieben, reicht nicht aus, denn die ‚Row Group‘ selbst bleibt wo sie ist und dann würde nur das Textfeld in eine andere Row Group verschoben. Im folgenden Negativbeispiel wurden nachträglich im Design-Bereich die Textfelder Intervall und Datenherkunft vertauscht. Dadurch sind sie in der jeweils falschen ‚Row Group‘ gelandet:

[[Datei:JasperReports-Handbuch_Eingebettet_010.png|642x387px]]


== Diagramme ==

Um einen Bericht ansprechend zu gestalten dürfen Diagramme wie Torten- oder Balkendiagramme nicht fehlen. Diese in einen Bericht einzubringen ist auch nicht schwer.

<blockquote>Vorab sei aber darauf hingewiesen: Grafiken in JasperReports arbeiten nicht analog zu Kreuztabellen, in denen Daten nach Zeilen- oder Spaltenmerkmalen automatisch gruppiert und summiert werden. Für Grafiken sollten Sie gewährleisten, dass die Datenbasis für die Grafik '''bereits gruppiert und summiert''' sind, Sie können also keine Einzeldaten für Grafiken verwenden. Bei Datenblatt-Berichten in Edustore ist dies gewährleistet, wenn Sie im Feld "Felder" nur die Felder selektieren, nach denen in der Grafik gruppiert werden soll.
</blockquote>

=== Einfache Diagramme ===

Nehmen wir an wir haben eine Tabelle, die die Studierendenzahl mehrerer Semester nach Geschlecht aufführt. Hier ein Screenshot der Datengrundlage:

[[Datei:JasperReports-Handbuch_jaspersoft_design_query3.png]]

Die Tabelle enthält die Merkmale Geschlecht, Semester und Summe. Daraus erzeugen wir in Jaspersoft Studio (und weiter unten in iReport) ein Balkendiagramm.


==== Einfache Diagramme in JasperSoft Studio ====

Zunächst definieren wir die Sortierung der Daten. Im "Dataset and Query Dialog" sind die Felder der Datenquelle aufgeführt. Unten finden Sie den Reiter "Sorting":

[[Datei:JasperReports-Handbuch_jaspersoft_design_query2.png]]

Damit die Grafik richtig funktioniert müssen wir nach beiden Merkmalen (Semester und Geschlecht) sortieren. Das Semester sollte nicht alphabetisch nach Namen sortiert sein, sondern nach dem Zahlenschlüssel. Sonst ständen alle Wintersemester untereinander, und davor alle Sommersemester.

Dann ziehen wir aus der Palette das Chart Element in das Summary Band. Es startet automatisch ein "Chart Wizward". Hier wählen wir "Stacked Bar" als Grafiktypen:

[[Datei:JasperReports-Handbuch_jaspersoft_design_chart_wizard1.png]]

Nun müssen wir ihm sagen welches Feld die Y-Achse darstellt (hier "Summe"), und welches die X-Achse (hier "Semester der Belegung"). Das Merkmal zur Unterscheidung der Balkenfarben ("Series") ist das Geschlecht:

[[Datei:JasperReports-Handbuch_jaspersoft_design_chart_wizard2.png]]

Danach klicken wir auf "Finish", und die Grafik wird als Platzhalter im Summary Band eingefügt. Dort definieren wir noch die Breite der Grafik:

[[Datei:JasperReports-Handbuch_jaspersoft_design_chart1.png]]

Damit ist der Entwurf fertiggestellt. So sieht die Grafik aus:

[[Datei:JasperReports-Handbuch_jaspersoft_design_chart_wizard3.png]]

Es ist etwas ungünstig dass die Labels der X-Achse nicht ganz lesbar sind. Wir lösen dies mit Rotation der Labels um 45 Grad:

[[Datei:JasperReports-Handbuch_jaspersoft_design_chart_wizard4.png]]

So sieht es besser aus:

[[Datei:JasperReports-Handbuch_jaspersoft_design_chart_wizard5.png]]

Das Beispiel lädt zur weiteren Verfeinerung an.


==== Einfache Diagramme in iReport ====

Hier die Ansicht in iReports "Refresh Preview Data":

[[Datei:JasperReports-Handbuch_designer_chart2.png]]

Die Spalten der Tabelle sind selbsterklärend. Nun ziehen wir aus dem "Report Elements" die "Chart" in das Band "Summary".

[[Datei:JasperReports-Handbuch_grafik_chart_in_summary_ziehen.png]]

Dabei öffnet sich ein Fenster in dem Sie sich die Art der Grafik auswählen können. In diesem Beispiel wählen wir "Stacked Bar 3D".

[[Datei:JasperReports-Handbuch_grafik_chart_auswaehlen.png]]

Nach dem Klick auf "OK", geht es weiter mit den Inhalten der Grafik.

Als Dataset gibt es hier nur eine Auswahl.

[[Datei:JasperReports-Handbuch_grafik_dataset_auswaehlen.png]]

Daher akzeptieren wir dies mit einem Klick auf "Weiter".

Die "Series" sind die verschiedenen Unterteilungen eines Balkens. Die "Series" sind die verschiedenen Unterteilungen eines Balkens. Wir wählen hier das Merkmal "Geschlecht":

[[Datei:JasperReports-Handbuch_designer_chart3.png]].

Bei der X-Achse (in JasperReports heißt das "Category Axis") nehmen wie das Merkmal Semester, und bei der "Value expression" die Summe.

[[Datei:JasperReports-Handbuch_designer_chart4.png]]

Damit ist die Definition beendet. Wir können dann in den Eigenschaften der Grafik noch eine "Title Expression" festlegen, z.B. "Studierende nach Semester und Geschlecht". In der Vorschau sieht die Grafik so aus:

[[Datei:JasperReports-Handbuch_designer_chart5.png]]

Die Wintersemester werden noch nicht abgedruckt, dazu ändern wie die "Label rotation" auf 30°. Dies lässt die Schrift unter den Balken rotieren, damit längere Schriftzüge möglich sind.

[[Datei:JasperReports-Handbuch_designer_chart6.png]]

Wichtig für die Grafik war die Sortierung in der Datenquelle nach "dim_semester.quell_id". Mit "Series Colors" kann man die Farbe der Balken ändern etc.

<blockquote>Wenn sie jeden Balken bzw. Teil des Balkens zusätzlich mit den Werten ausgeben wollen, müssen sie in den Chart-Eigenschaften unter den "Bar*Properties" das Ankreuzfeld "Show labels" ankreuzen. Wenn es bereits angekreuzt ist, sollten Sie das Kreuz einmal entfernen und wieder setzen (Bug in iReport seit Version 4.x)
</blockquote>

=== Diagramme nach Tabelle ausgeben ===

Üblicherweise ähnelt ein Diagramm in JasperReports einer Kreuztabelle. Wenn nun ein Diagramm nach Vorgabe einer Tabelle ausgegeben werden soll, muss ein wenig getrickst werden.

Erläuterung:

In der Series expression werden die Zeilen angegeben.

In der Category expression werden die Spalten angegeben.

In der Value expression wird der Wert angegeben.

Um ein Diagramm nun zu erstellen muss pro Series + Category eine Categorie series angelegt werden und das entsprechende Feld angegeben werden.


=== Diagramme mit berechneten Werten ===

Wenn die einem Diagramm zugrunde liegende Tabelle noch Berechnungen erfordert, muss man mit Variablen arbeiten. Als Beispiel wird hier die Maske "Studierende und Studienanfänger (Zeitreihe)" benutzt. Das Ergebnis wird eine Tabelle mit Balkendiagramm der "Studierende und Studienanfänger im 1. Fachsemester (Zeitreihe)" sein.

Ein bereits fertiges Datenblatt könnte folgendermaßen aussehen:

[[Datei:JasperReports-Handbuch_grafik_datenblatt_ohne_grafik.jpg]]

Hier fehlt jetzt die Grafik, die in dem noch leeren Band "Summary" eingefügt werden soll. Wenn das Band noch nicht eingefügt wurde, einfach mit Rechtsklick auf Summary (im "Report Inspector") und dann auf "Add Band" um es anzuzeigen.

[[Datei:JasperReports-Handbuch_grafik_how_to_add_summary.png]]

Nun ziehen wir aus dem "Report Elements" die "Chart" in das Band "Summary".

[[Datei:JasperReports-Handbuch_grafik_chart_in_summary_ziehen.png]]

Dabei öffnet sich ein Fenster in dem Sie sich die Art der Grafik auswählen können. In diesem Beispiel wählen wir "Stacked Bar 3D".

[[Datei:JasperReports-Handbuch_grafik_chart_auswaehlen.png]]

Nach dem Klick auf "OK", geht es weiter mit den Inhalten der Grafik.

Als Dataset gibt es hier nur eine Auswahl.

[[Datei:JasperReports-Handbuch_grafik_dataset_auswaehlen.png]]

Daher akzeptieren wir dies mit einem Klick auf "Weiter".

Die "Series" sind die verschiedenen Unterteilungen eines Balkens. Da es in diesem Beispiel dafür keine Variable gibt, wird später noch per Hand eine Weitere hinzugefügt. Wenn es bei Ihnen möglich ist, klicken Sie rechts neben dem Feld auf den Button und fügen dort eine Variable ein. In diesem Beispiel wird als fester String "Frauen im 1. FS" eingegeben.

[[Datei:JasperReports-Handbuch_grafik_series_auswaehlen.png]]

Und dann wieder auf "Weiter".

Auf der X-Achse soll in diesem Beispiel die Semester erscheinen und auf der Y-Achse die Anzahl der Weiblichen Studierenden im 1. Fachsemester. Um dies zu erhalten wählt man als "category expression" die Variable "Semester" aus.

[[Datei:JasperReports-Handbuch_grafik_category_auswaehlen1.png]]

Dies geschieht, indem man auf den Button rechts neben dem Feld klickt,

[[Datei:JasperReports-Handbuch_grafik_category_auswaehlen2.png]]

dann doppelt auf das Feld "Semester" klickt und dann auf "Apply".

In den meisten Fällen werden hier Felder benutzt. Wenn Sie jedoch z.B. eine Variable benutzen wollen, müssen Sie nach dem Klick rechts auf den Button in dem neuen Fenster links unten z.B. auf "Variables" oder "Parameter" klicken. Dabei ändert sich der Inhalt von dem mittleren Feld.

[[Datei:JasperReports-Handbuch_grafik_category_auswaehlen3.png]]

Hier können Sie nun auch eine andere Auswahl treffen.

Das selbe gilt auch für "value expression". Der Unterschied ist hierbei, die "category expression" ist die Bezeichnung und in "value expression" dürfen nur Zahlen vorkommen, welche von JasperReports addiert werden können.

[[Datei:JasperReports-Handbuch_grafik_value_auswaehlen1.png]]

Hier wählen wir nun z.B. das Feld "1. FS Frauen" aus.

[[Datei:JasperReports-Handbuch_grafik_value_auswaehlen2.png]]

Nun noch abschließend auf Beenden drücken und wir erhalten das erste Ergebnis. Über "Preview" wird nun das Diagramm mit den Frauen aus dem 1. Fachsemester über die Semester angezeigt.

[[Datei:JasperReports-Handbuch_grafik_erstes_ergebnis.png]]

Um nun die männlichen Studenten aus dem 1. FS noch hinzuzufügen oder Änderungen an der gerade getroffenen Auswahl vorzunehmen klickt man mit der rechten Maustaste auf die Chart und dann auf "Chart Data". In dem Reiter "Details" kann man nun die eben angelegte Category bearbeiten/entfernen oder auch eine neue anlegen.

[[Datei:JasperReports-Handbuch_grafik_chart_details.png]]

Hier wollen wir jetzt noch die männlichen Studierende aus dem 1. FS noch Hinzufügen. Also klickt man auf "Hinzufügen.

[[Datei:JasperReports-Handbuch_grafik_chart_m_std_1fs_hinz.png]]

Die Eingabe funktioniert hier genau wie in dem Assistenten bei der Erstellung einer neuen Chart. Nur taucht jetzt das Problem auf, dass es kein Feld mit den Männlichen Studierenden gibt, sondern nur gesamt. Die Lösung ist aber ganz einfach. Zunächst geht man wieder in den "Expression editor" der "Value expression" und wählt das Feld "1. FS gesamt" aus, setzt dahinter ein Minuszeichen und danach wählt man noch das Feld "1. FS Frauen" aus. Jasper berechnet dann jeweils das Ergebnis und benutzt dieses als Value.

[[Datei:JasperReports-Handbuch_grafik_chart_m_std_1fs_hinz_1.png]]

Nun erhalten wir als Ergebnis folgende Tabelle:

[[Datei:JasperReports-Handbuch_grafik_zweites_ergebnis.png]]

Es gibt noch viele Änderungsmöglichkeiten unter Einstellungen wie z.B. "Label rotation" lässt die Schrift unter den Balken rotieren, damit längere Schriftzüge möglich sind und "Series Colors" um die Farbe der Balken zu ändern.

[[Datei:JasperReports-Handbuch_grafik_zweites_ergebnis1.png]]


=== Chart Customizer ===

Mit JasperSoft Studio können die über sog. "Chart Customizer" Details bzgl. des Layouts vor Diagrammen steuern. Im folgenden ein Beispiel:

Wir haben ein einfaches Balkendiagramm, in dem wir eine (automatisch) ermittelte Y-Achse mit Werten von 0-15 haben:

[[Datei:JasperReports-Handbuch_jr_chart_customizer_range1.png]]

Nun wollen wir den Bereich auf 12 (in 2er-Schritten ändern). Man könnte dies ganz leicht über die Eigenschaften ändern:

[[Datei:JasperReports-Handbuch_jr_chart_customizer_range2a.png]]

Hier kann man aber nicht die Schrittweite ändern. Wir legen dazu einen Chart Customizer vom Typ "Value Axis Range and Tick" an:

[[Datei:JasperReports-Handbuch_jr_chart_customizer_range2.png]]

und damit sieht das Diagramm so aus:

[[Datei:JasperReports-Handbuch_jr_chart_customizer_range3.png]]

Die Y-Achse zählt nun in 2er Schritten von 0 bis 12.

<blockquote>Noch ein Hinweis: Bei Y-Achsen mit kleinen Wertebereichen kann es vorkommen, dass JR die Y-Achse automatisch mit Intervallen mit Nachkommastellen versieht, also z.B. 1 - 1,5 - 2 - 2,5 etc. Bei manchen Maßen macht die Nachkommastelle keinen Sinn (z.B. wenn Studierende gezählt werden). Um das zu ändern gehen Sie in der Eigenschaften der Y-Achse (Chart → Value axis) und setzen bei der Eigenschaft "Value axis tick label mask" den Wert "#" (Pattern für ganzzahlig) ein. Damit wird nur noch ganzahlig hochgezählt.
</blockquote>

=== Balken Labels ===

In Balkendiagrammen können die exakten Zahlen nicht genau ermittelt werden. Aus diesem Grund wird oft gewünscht, die Zahlen noch mal schriftlich darzustellen.

[[Datei:JasperReports-Handbuch_balken_labels_1.png]]

Um die Zahlen anzeigen zu lassen muss einfach in den Chart Properties unter Advanced „Common Chart Properties → Plot → Show Labels“ auf true gesetzt werden.


== Booklets ==

Ab JR 6.2 oder höher (d.h. SuperX-Kernmodul 4.8 oder HISinOne-BI 2018.12) gibt es die Möglichkeit, Berichts-"Bücher" mit Deckblatt, Inhaltsverzeichnis und Schlußseite zu erstellen. Die Erstellung ist übersichtlicher als eine Kombination aus Haupt- und Unterbericht, und bietet beim Seitenlayout mehr Optionen, z.B. kann man in einem Booklet Hoch- und Querformat kombinieren.

Englische Anleitungen siehe

https://community.jaspersoft.com/documentation/tibco-jaspersoft-studio-user-guide/v60/report-books

Wg. der Version ist diese Möglichkeit in iReport nicht mehr verfügbar, Sie müssen JasperSoft Studio nutzen. Wenn Sie dort mit File -> New einen neuen Report erzeugen, können Sie bei Report type den Wert "Book report" wählen. Der Assistent fragt Sie dann, ob Sie Deckblatt, Inhaltsverzeichnis und die Schlußseite benötigen, kreuzen Sie die jew. Position an. Sie erhalten danach ein Entwurfsfenster mit dem Hauptbericht, der drei Abschnitte enthält: Das Deckblatt und Inhaltsverzeichnis ("Cover and table of contents"), den Buchinhalt ("Content") und die Schlußseite ("Backcover"):

[[Datei:JasperReports-Handbuch_booklet_main1.png]]

Wenn Sie die Datei speichern, werden die jew. Unter-Dateien automatisch mit angelegt, mit dem Zusatz "*_cover.jrxml", "*_toc.jrxml" und "*_backcover.jrxml".


=== Hauptbericht im Booklet ===


==== Aufbau des Hauptberichts ====

Startpunkt beim Booklet ist der Hauptbericht. Dieser hat keine "Bänder" im Sinne einer Ergebnisausgabe, insbesondere gibt es kein Detailband. Trotzdem arbeitet der Hauptbericht mit einer Datenquelle im Sinne eines Detailbandes, hier heißt das Band "Content". Für Makroberichte in SuperX-/BI müssen wir für alle Unterberichte dieselbe XML-Quelle verwenden, d.h. wir müssen im Hauptbericht genau eine Zeile der XML-Quelle filtern. Wir machen das mit XPATH mit dem Ausdruck 

/ergebnisse/ergebnis[@ordnr='0']/ergebniselement/sqlerg/row[@no='0']

Dies liefert die erste Zeile der ersten Tabelle des Makroberichts im Ergebnis.

Klicken Sie also oben auf die Datenquelle des Hauptberichts, und fügen Sie den Filter ein:

[[Datei:JasperReports-Handbuch_booklet_main2.png]]

Die Funktion „Read Fields“ funktioniert in diesem Fall nicht. Die Felder für den Hauptbericht werden manuell in den Sourcecode eingefügt. Dazu erstellen Sie zunächst, wie in [[#4.5.Makroberichte als Datenquelle für JasperReports|outline|Abschnitt 4.5]] beschrieben, ein JR-Template für den Makrobericht. Aus diesem Template kopieren Sie aus dem Sourcecode die Felder und fügen diese im Booklet ein. Fügen Sie alle Felder sowohl im Haupt- als auch in den Unterberichten des Booklets ein.

Im Content Band können Sie dann mit der rechten Maustaste die jew. Unterberichte verlinken. Die Technik ist identisch mit den normalen Haupt/-Unterberichten, nur dass das Seitenlayout nicht vom Hauptbericht zum Unterbericht vererbt wird.

Im Beispiel haben wir einen Unterbericht verlinkt:

[[Datei:JasperReports-Handbuch_booklet_main3.png]]

Im Feld "Component Expression" geben Sie den Unterbericht an. Im Feld "Tab name expression" können Sie den Namen des TABs in Excel definieren. Standardmäßig wird bei einem Booklet beim Export nach Excel also ein Arbeitsblatt mit mehreren Sheets.

Der Unterbericht wird mit den gleichen Parametern aufgerufen wie bei klassischen [[#2.5.1.Konfiguration des Hauptberichts|outline|Unterberichten]]. Der erste Unterbericht bekommt die ordnr 0, der zweite Unterbericht die ordnr 1 usw.:

[[Datei:JasperReports-Handbuch_booklet_main4.png]]


=== Übergabe von Layouts vom Hauptbericht an Unterberichte ===

Generell werden im Booklet keine Layoutvorgaben vom Hauptbericht an den jew. Unterbericht übergeben. Ausnahme: Die Property "net.sf.jasperreports.export.xls.detect.cell.type", die beim Excel Export als Zahl formatierte Zellen auch in Excel als Zahl ausgibt, wird im Hauptbericht gesetzt und dann an die Unterberichte übergeben.

Achtung: Je nach JasperSoft Studio Version kann man diese Property nicht in der graphischen Entwcklungsumgebung setzen, sondern nur im *.jrxml-Quellcode.


=== Booklet Deckblatt ===

Das Deckblatt ist ein normaler JasperReport mit Elementen im Titel-Band. Beachten Sie dass im Unterbericht auch Seitenränder und Seitenformate definiert sein müssen. Sie können auch vom Hauptbericht Parameter übergeben, hier z.B. das Semester:

[[Datei:JasperReports-Handbuch_booklet_cover1.png]]

Im Hauptbericht wiederum wird dieser Parameter dann übergeben, hier z.B. aus der Legende der Maske:

[[Datei:JasperReports-Handbuch_booklet_cover2.png]]


=== Booklet Inhaltsverzeichnis ===

Das Inhaltsverzeichnis ist ein Bericht ohne Datenquelle, und bekommt über die Evaluation Time="Report" die Anweisung, die Inhaltsdokumente nach Lesezeichen (HTML-Anchors) zu durchsuchen.

[[Datei:JasperReports-Handbuch_booklet_toc1a.png]]

Die Datenquelle ist leer, und über die Property

net.sf.jasperreports.bookmarks.data.source.parameter=REPORT_DATA_SOURCE

wird als Datenquelle der Content angegeben.

[[Datei:JasperReports-Handbuch_booklet_toc1b.png]]

Das Berichtsdesign ist vom Assistenten vorgegeben und relativ einfach. Sie können bis zu drei Ebenen für das Inhaltsverzeichnis angeben, jede Ebene benötigt ein eigenes Detailband.

[[Datei:JasperReports-Handbuch_booklet_toc2.png]]

Die Feldnamen im Bericht sollten nicht geändert werden. Sie können aber das Layout anpassen.


=== Booklet erster Detailbericht ===

Der Detailbericht ist ein normaler Unterbericht, d.h. er hat den Parameter "ordnr":

[[Datei:JasperReports-Handbuch_booklet_content1.png]]

Die Variable "ordnr" wird dann bei der Datenquelle des Unterberichts ausgewertet:

[[Datei:JasperReports-Handbuch_booklet_content2.png]]

Der Unterbericht soll sicherlich auch Seitenzahlen anzeigen, dazu fügen Sie noch ein "Page footer" Band hinzu, und erzeugen dort ein Textfeld mit dem Inhalt z.B.

"Seite "+$V{MASTER_CURRENT_PAGE}

Das Textfeld muss bei Evaluation time den Wert "Master" haben.

[[Datei:JasperReports-Handbuch_booklet_content3.png]]

Danach wird die Seitenzahl jedes Unterberichts an den Hauptbericht angepaßt.

Für das Inhaltsverzeichnis müssen Sie im jew. Detailbericht Lesezeichen (HTML-Anchors) und jeweils eine Ebene angeben. Wir können z.B. für das Textfeld der Überschrift einen Anker der Ebene 1 festlegen:

[[Datei:JasperReports-Handbuch_booklet_content4.png]]

Danach legen wir für das Gruppenband für das Textfeld mit dem Label der Gruppe (Fakultätsname) einen Anker der Ebene 2:

[[Datei:JasperReports-Handbuch_booklet_content6.png]]


=== Das fertige Booklet ===

So sieht das Booklet im Preview im JasperSoft Studio aus: Zuerst das Deckblatt...

[[Datei:JasperReports-Handbuch_booklet_preview1.png]]

... und dann auf Seite 2 das Inhaltsverzeichnis:

[[Datei:JasperReports-Handbuch_booklet_preview1b.png]]

und dann auf Seite 3 der erste Unterbericht:

[[Datei:JasperReports-Handbuch_booklet_preview2.png]]


== Schriften ==


=== Allgemeines zu Schriften ===

Für den Entwurf von Berichten ist es wichtig, daß die jew. Schriftart auch beim Server-System und beim Client verfügbar sind.

<blockquote>Ein häufiger Fallstrick ist hier: unter Windows wird mit JasperReports entworfen, und dort z.B. die Schriftart "Arial" gewählt. Der Report soll auf dem Server unter Linux laufen, dort gibt es die Schriftart nicht. Resultat: der Bericht ist nicht kompilierbar.
</blockquote>
Bei PDF-Dateien lassen sich Fonts ggf. auch in die Datei einbetten, bei Exportformaten wie OpenOffice oder Word ist dies nicht möglich. Sie sollten daher Schriftarten wählen, die auch beim Client mit größter Wahrscheinlichkeit installiert sind. Die sicherste Wahl ist es, Font-Familien anzugeben, z.B. "Serif".

Im Zweifelsfall installieren Sie die Schriftart auf allen beteiligten Systemen. TrueType Fonts lassen sich in JasperReports importieren und nutzen, sie können sogar in PDF-Dateien standardmäßig eingebettet werden. Im folgenden wird die Schriftart "Liberation Sans" installiert, die man auf [https://fedorahosted.org/liberation-fonts/ https://fe][https://fedorahosted.org/liberation-fonts/ dorahosted.org/liberation-fonts/] herunterladen kann. Entpacken Sie das Download Paket in einem beliebigen Verzeichnis.


=== Schriften in iReport einbinden ===

Achtung: wenn Sie iReport unter Windows nutzen, müssen Sie für die folgenden Schritte iReport als Admin starten:

Im Menü "Extras"->"Optionen" können Sie den Font importieren:

[[Datei:JasperReports-Handbuch_font_import_step1.png]]

Wählen Sie aus der Dateiliste zunächst den "Regular"-Font aus, z.B. die Sans-Serif-Variante. Im nächsten Schritt geben Sie dem Font einen Namen, und Sie wählen die zugehörigen Dateien für Fettdruck etc:

[[Datei:JasperReports-Handbuch_font_import_step2.png]]

Außerdem kreuzen Sie an, daß der Font in die jew. PDF-Datei eingebettet wird. Die nächsten zwei Dialoge (Locales, Font Mappings) lassen wir der Einfachheit halber erstmal weg. Wenn Sie dann OK drücken, ist der Font in iReport installiert. Sie können die Einstellungen jederzeit ändern, indem Sie auf "Edit Font" klicken:

[[Datei:JasperReports-Handbuch_font_import.png]]

Hier die Ansicht, wenn Sie auf "Edit Font" klicken:

[[Datei:JasperReports-Handbuch_font_import1.png]]

Am Ende des Formulars können Sie noch PDF-Exportoptionen wählen, z.B. ob die Schriftart in PDF-Dateien eingebunden werden soll. Achtung: beachten Sie lizenzrechtliche Fragen, die wenigsten Fonts sind ohne weiteres kopierbar. Wir empfehlen den Liberation-Font, der steht unter der OpenSource Lizenz GPL.


=== Schriften in '''JasperSoft Studio''' einbinden ===

Unter „Window“ → „Preferences“ können Sie Fonts einbinden:

[[Datei:JasperReports-Handbuch_font_import4.png]]

Nach einem Klick auf „Add“ öffnet sich ein neues Fenster. Dort geben Sie dem Font einen Namen und wählen die zugehörige Datei für den normale Ausführung des Fonts. Es gibt weitere Reiter für Bold, Italic und Bold Italic:

[[Datei:JasperReports-Handbuch_font_import5.png]]

Außerdem kreuzen Sie an, daß der Font in die jew. PDF-Datei eingebettet wird. Die nächsten zwei Dialoge (Locales, Font Mappings) lassen wir der Einfachheit halber erstmal weg. Wenn Sie dann OK drücken, ist der Font in iReport installiert.

Sie können die Einstellungen jederzeit ändern, indem Sie auf "Edit Font" klicken:

[[Datei:JasperReports-Handbuch_font_import6.png]]

Achtung: Beachten Sie lizenzrechtliche Fragen, die wenigsten Fonts sind ohne weiteres kopierbar. Wir empfehlen den Liberation-Font, der steht unter der OpenSource Lizenz GPL.


=== Default-Schriftart in iReport ===

Sie können die Default Schriftart in iReport einstellen:

[[Datei:JasperReports-Handbuch_ireport_default_font.png]]

Stellen Sie den Default-Font auf "Liberation Sans". Danach müssen Sie iReport neu starten.


=== Fonts auf dem Server ===

Um Schriftarten auf einen Tomcat-Server zu installieren, müssen die vier ttf-Dateien (normal, fett, kursiv, fett-kursiv) in den Ordner $JRE_HOME/lib/fonts kopiert werden. Für alle Java Anwendungen wie den Tomcat und JasperReports stehen dann die in dem verwendetem Java zur Verfügung.

Beispiel Arial unter Ubuntu 18.04:

Prüfen Sie mit dem Kommando

ps fax | grep tomc

welcher Tomcat läuft. Sie bekommen eine Ausgabe z.B.

47769 ? Sl 36:25 /usr/lib/jvm/java-8-openjdk-amd64/bin/java -Djava.util.logging.config.file=/var/lib/tomcat8/conf/logging.properties -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Djdk.tls.ephemeralDHKeySize=2048 -Djava.protocol.handler.pkgs=org.apache.catalina.webresources -Xmx3500M -XX:MaxPermSize=400m -Djava.awt.headless=true -Dfile.encoding=UTF-8 -DSuperX-DB-PROPERTIES-SET=true -Djava.endorsed.dirs=/var/lib/tomcat8/endorsed -classpath /var/lib/tomcat8/bin/bootstrap.jar:/var/lib/tomcat8/bin/tomcat-juli.jar -Dcatalina.base=/var/lib/tomcat8 -Dcatalina.home=/var/lib/tomcat8 -Djava.io.tmpdir=/var/lib/tomcat8/temp org.apache.catalina.startup.Bootstrap start

Der erste Befehl zeigt den Pfad zu JRE_HOME, also /usr/lib/jvm/java-8-openjdk-amd64. Sie kopieren also die Dateien z.B.

arial.ttf

arialbd.ttf

arialbi.ttf

ariali.ttf

von

C:\Windows\winsxs\amd64_microsoft-windows-font-truetype-arial_31bf3856ad364e35_6.1.7601.17514_none_d0a9759ec3fa9e2d\*.ttf

nach

/usr/lib/jvm/java-8-openjdk-amd64/lib/fonts

und starten dann Tomcat neu.

<blockquote>Achtung: Sorgen Sie dafür dass Sie eine Lizenz für die jew. Fonts haben, weil diese bei PDF in die ausgelieferten Dateien eingebettet werden.
</blockquote>

=== Font Extension ===

Eine Alternative zu dem Einbinden der Schriftart über das Java Verzeichnise Font Extension. Diese hat aber nicht immer funktioniert. Um auf diesem Wege die Fonts auf einem Ziel-Server einzubinden, kann man die Schriftart als Font Extension exportieren, die dann wiederum in den CLASSPATH des Servers (bei Webanwendungen WEB-INF/lib) kopiert werden müssen:

[[Datei:JasperReports-Handbuch_font_import2.png]]

Nutzen Sie dazu den obigen Button "Export as extension", und wählen Sie einen Dateinamen mit der Endung ".jar".

<blockquote>Hinweis: Die Einbettung einer Font Extension in einer JasperReports-Laufzeitumgebung klappt erst mit JasperReports 3.7.2 oder höher.
</blockquote>
Wenn Sie in iReport auch PDF als Vorschau wählen, erzeugt iReport im Verzeichnis der jrxml-Datei auch eine entsprechende PDF-Datei. Damit diese die Fonts enthält, müssen Sie auch in iReport im CLASSPATH die Font-Extension einbinden. In diesem Falle ist es vorteilhaft, die Endung ".jar" (nicht ".zip") zu wählen, weil iReport hier nur jar-Dateien einbindet.

Noch ein Hinweis zu den Attributen "PDF Font name" und "PDF Encoding":

[[Datei:JasperReports-Handbuch_font_import3.png]]

Diese Attribute werden nicht mehr ausgewertet, wenn Sie mit Font Extensions arbeiten.


== TextField-Formatierung ==

In diesem Abschnitt werden verschiedene Einstellungen und Möglichkeiten der Formatierung in TextFields vorgestellt und erläutert.


=== Ausgabe von '''NULL''' als '''String''' verhindern ===

Falls NULL in einem TextField als String ausgeschrieben wird, kann dies verhindert werden, indem die Einstellung „Blank When NULL“ aktiviert wird. Das Feld bleibt dann leer:

[[Datei:JasperReports-Handbuch_text_field_formatting.png]]


=== Einzelne Wörter unterstreichen oder fett drucken ===

Wenn in einem TextField einzelne Wörter unterstrichen oder fett gedruckt werden sollen, einfach in den „Text properties“ unter „Markup“ „styled“ auswählen. In dem Textfield dann einfach um das zu unterstreichende Wort „ … “ schreiben oder „ … “ um es fett gedruckt auszugeben.

<blockquote>Bitte beachten, dass die PDF-Preview aus Jaspersoft Studio heraus keinen Fettdruck darstellt.
</blockquote>

=== Zahlen- und Datumsformat ===

Die Formatierung der Werte kann mit Hilfe des Attributes "Pattern" gesetzt

werden. Hier ein Beispiel:

[[Datei:JasperReports-Handbuch_textfield_pattern1.png]]

Das Textfeld bekommt das Pattern "0", d.h. es wird eine Ganzzahl inkl. 0 angezeigt. Der Platzhalter "#" steht für Zahlenbestandteile, hier wird eine 0 allerdings nicht angezeigt. Weitere Zahlen- und Datumsformate sind im Assistenten (linker Teil des Screenshots) sicher selbsterklärend.


=== Pattern Expression ===

Hat man pro Spalte / Zelle unterschiedliche Werte z.B. Datumsangaben und Währungseinheiten

oder Ganzzahlen und Kommazahlen und möchte diese unterschiedlich formatieren, so kann dies

mit dem Attribut "Pattern Expression" dargestellt werden.

Hier ein Beispiel für die Ausgabe von Ganzahlen und Kommazahlen:

$V{valueMeasure}.doubleValue() == Math.floor($V{valueMeasure}.doubleValue()) &&

!Double.isInfinite($V{valueMeasure}.doubleValue()) ?

"#0;#0" : "###0.00;###0,00"

Hier der Pattern Expression Editor:

[[Datei:JasperReports-Handbuch_ireport_pattern_expression_editor.png]]

Hier das Ergebnis:

[[Datei:JasperReports-Handbuch_ireport_pattern_expression_ergebnis.png]]


== Effiziente Formatierung ==

Wenn Sie keine Lust haben, jedes Textelement eines Berichts einzeln zu formatieren, empfehlen wir als ersten Schritt, Formatierungen zu kopieren.

Im Kontextmenü jedes Elements gibt es die Menüpunkte "Copy Format" und "Paste Format", die jeweils Formate kopieren und einfügen.

[[Datei:JasperReports-Handbuch_copy_format.png]]

Für Hochschulen ist ein einheitliches Layout der Berichte wichtig, und so bietet es sich an, zentrale Layouts zu definieren und dann wiederzuverwenden. In JasperReports heißen Layouts auch "Styles" bzw. Formatvorlagen. Ähnlich wie in OpenOffice Writer oder MS Word lassen sich Formatvorlagen definieren und zuweisen. Bei Änderungen der Formatvorlage werden diese Änderungen auf alle Elemente automatisch übertragen - auch nachträglich.

In der "Styles Library" werden z.B. einige häufig verwandte Layoutvorlagen angeboten.

[[Datei:JasperReports-Handbuch_styles_library.png]]

Sie können die Formate anwenden, indem Sie einfach die jew. Vorlage von der "Styles Library" per Drag and Drop auf das Ziel-Textfeld im Report Design ziehen und somit anwenden.

Sie können auch eigene Formatvorlagen zentral definieren. Im Menü Datei->New->Style geht es los: Wir erzeugen z.B. eine neue Style-Datei mit dem Namen "meinLayout.jrtx":

[[Datei:JasperReports-Handbuch_style_def_folie.png]]

In der jrtx-Datei definieren sie einen oder mehrere Formatvorlagen. Wir definieren z.B. die Formatvorlage "Textelemente", und geben ihr die Eingenschaft "SansSerif, Schriftgröße 12".

Danach können sie die Datei in der jrxml-Datei im Report Inspector unter "Styles" einbinden. Damit sind die Formatvorlagen in dieser Datei verfügbar, und können bei den Elementeigenschaften im Attribut "Style" zugewiesen werden:

[[Datei:JasperReports-Handbuch_styleref_design_folie.png]]

JasperReports nimmt standardmäßig den absoluten Pfad der jrtx-Datei, in der XML-Quelle sollten Sie diesen Pfad auf relativ umstellen.


== Conditional styles – '''Bedingte Formatierung''' ==

Wenn man in einzelne Textfelder "bedingte Formatierung" nutzen will (z.B. farbiger Hintergrund, Fettdruck), hat man früher mehrere Textfelder einzeln angelegt, mit dem gleichen Inhalt und einer jeweiligen "Print-when expression". Das geht seit JR 3.x eleganter mit den sog. "Conditional styles".

Hierfür wird ein Style angelegt und diesem diverse „Conditional Styles“ untergeordnet. Die „Conditional Styles“ enthalten Bedingungen und Formatierungseinstellungen. Der Style kann beispielweise einem Textfeld übergeben werden. Sobald die Bedingung eines „Conditional Styles“ erfüllt wird, werden die im „Conditional Style“ festgelegten Formatierungseinstellungen auf das Textfeld angewandt. Die Einstellungen im Textfeld selbst werden allerdings höher priorisiert. Eine detaillierte Erläuterung der Priorisierung anhand eines Beispiels findet sich in Abschnitt „Textfeld vs. Conditional Style – Priorisierung“


=== Beispiel in JasperSoft Studio – Schrift fett machen ===

Zunächst legen Sie die Formatierungen an, indem Sie unter Styles die rechte Maustaste drücken und über „Create Style“ einen Style erstellen, beispielsweise '''Daten_angepasst'''.

[[Datei:JasperReports-Handbuch_cond_style3.png]]

Durch Rechtsklick auf '''Daten_angepasst''' wird über „Create Conditional Style“ ein neuer Conditional Style hinzugefügt. Es erscheint ein neuer Unterknoten <No condition set>. Über die Properties können anschließend die zu erfüllende Bedingung als Expression, beispielsweise

''$F{Name}.equals("Summe Aktiva")||$F{Name}.equals("Summe Passiva")''

festgelegt und die Formatierungseinstellungen vorgenommen werden. In diesem Falle ist Fettschrift (bold) gewählt :

[[Datei:JasperReports-Handbuch_cond_style4.png]]

Um den Style inklusive seiner Conditional Styles auf beispielsweise ein Textfeld anzuwenden, werden die Properties des entsprechenden Feldes geöffnet. Im Reiter Appearance wird der gewünscht Style, in diesem Falle '''Daten_angepasst''',''' '''dem Textfeld zugeordnet:

[[Datei:JasperReports-Handbuch_cond_style5.png]]

Bei mehreren conditional styles wird die Reihenfolge ausgewertet, alle zutreffende conditional styles werden genommen. Die Reihenfolge wird direkt im XML oder per Drag&Drop geändert.

Es kam in der Vergangenheit bereits zu dem Phänomen, dass im Conditional Style Fettschrift gewählt war, aber nicht ins Textfeld übernommen wurde, während beispielsweise Kursivschrift problemlos und wie erwartet funktionierte. Eine genauere Beschreibung und Lösung findet sich im Abschnitt „Textfeld vs. Conditional Style – Priorisierung“


=== Beispiel in iReport – Schrift fett machen ===

Um z.B. einzelne Zeilen nach einer Bedingung fett zu machen oder nicht kann man so vorgehen: Zunächst legen Sie die Formatierungen an, indem Sie im Report Inspector unter Styles die rechte Maustaste drücken und ein Style hinzufügen, z.B. '''zw_maybe_bold''' für einen Style der Fett sein soll, wenn im Feld '''zw''' bestimmte Werte stehen.

[[Datei:JasperReports-Handbuch_styles.png]]

Danach erzeugen Sie mit Rechtsklick auf '''zw_maybe_bold''' eine neue Bedingung mit „Hinzufügen von Conditional Style“. Bei dem neuen Unterknoten <No condition set> klicken Sie auf die rechte Maustaste, dann Edit Condition. Hier können Sie wie gewohnt eine Bedingung in Form einer Expression eingeben, z.B.

$F{Zweckbestimmung}.equals("Gesamtausgaben")||$F{Zweckbestimmung}.equals("Gesamteinnahmen")

Dann müssen Sie den neuen Conditional Style anklicken

[[Datei:JasperReports-Handbuch_cond_style.png]]

und in den Eigenschaften bold auf true setzen.

Dann wählt man im Report designer die Felder aus, die ggfs. fett dargestellt werden sollen, und bei den Eigenschaften als Style '''zw_maybe_bold'''.

[[Datei:JasperReports-Handbuch_cond_style2.png]]

Wenn man mit Padding arbeiten will, kann man für den Style padding angeben, muss aber anscheinend manuell im jrxml leftpadding entfernen

<box topPadding="0" <s>leftPadding="0"</s> bottomPadding="0">

Bei mehreren conditional styles wird die Reihenfolge ausgewertet, alle zutreffende conditional styles werden genommen. Es gibt zwar einen Menüpunkt „Reihenfolge ändern“ bei rechtem Mausklick, der ist jedoch deaktiviert, man kann die Reihenfolge aber direkt im XML ändern oder per Drag&Drop.

Leider kann man nicht einen conditionalstyle auf ein leere Zelle anwenden (z.B. Unterstrich), wenn man Excelexport macht, wird daraus einfach eine leere Zelle ohne Formatierung selbst wenn man Leerzeichen in der Text Expression hat.

Werden Variablen im conditional style verwendet, muss die evaluation time aktiviert werden über die property:

<property name="net.sf.jasperreports.style.evaluation.time.enabled" value="true"/>

Siehe https://community.jaspersoft.com/blog/tip-data-set-variable-usage-conditional-style-table-component-jasper-reports

Ein Style kann auch mit einem anderen Style verknüpft werden, indem in dem entsprechenden Style unter dem Reiter „Style“ in dem Feld „Style“ das entsprechende Style ausgewählt wird. Somit können bestimmte Wiederholungen gespart werden.


=== Textfeld vs. Conditional Style – Priorisierung ===

In diesem Abschnitt wird anhand eines Beispiels aufgezeigt, dass Textfelder höher priorisiert sind als Conditional Styles und welche Fallstricke dadurch entstehen können. Das Beispiel:

Einem Textfeld wird ein Style zugeordnet, der einen Conditional Style enthält, welcher bei erfüllter Bedingung den Text fett und kursiv darstellen soll:

[[Datei:JasperReports-Handbuch_cond_style6.png]]

Im Textfeld selbst sind beide Einstellungen deaktiviert:

[[Datei:JasperReports-Handbuch_cond_style7.png]]

Das Ergebnis ist, dass im Bericht der Text dieses Feldes zwar kursiv, aber nicht fett dargestellt wird. Zum Testen werden weitere Formatierungseinstellungen im Conditional Style hinzugefügt, beispielsweise Unter- und Durchstreichen und auch dies wird umgesetzt. Die Bedingung des Conditional Styles ist also erfüllt.

Der Grund für dieses Verhalten ist nur mit Blick auf den Source-Code ersichtlich:

[[Datei:JasperReports-Handbuch_cond_style8.png]]

Dort findet sich in den Einstellungen des Textfeldes ''isBold=“false“''. Dieses Fragment ist dadurch entstanden, dass in der Designoberfläche von JasperSoft Studio für das Textfeld die Einstellung bold einmal aktiviert und dann wieder deaktiviert wurde. Im Source-Code wird nach dem ersten Aktivieren ''isBold=“true“'' hinzugefügt und beim Deaktiveren nicht wieder komplett entfernt, sondern auf false gesetzt. Da die Einstellungen im Textfeld selbst höher priorisiert werden, als jene der Conditional Styles, wird der Fettdruck des Conditional Styles nicht umgesetzt. Löscht man im Source-Code das Fragment ''isBold=“false“'', dann wird der im Conditional Style definierte Fettdruck umgesetzt.


=== Default Style ===

Es ist möglich einen Style als Default Style zu verwenden. Hierfür wird beim Style, nicht beim Conditional Style, die entsprechende Einstellung gesetzt:

[[Datei:JasperReports-Handbuch_cond_style9.png]]

Dieser Style wird nun auf jedes Feld angewandt, dem kein anderer Style zugeordnet ist.


== Expression Editor ==

Im Expression Editor werden die für die Ausgabe bestimmten Werte angegeben. Zahlen werden ohne Zusatz eingetragen. Feste String Werte werden zwischen Anführungszeichen gesetzt. Felder und Variablen können über ein Doppelklick auf den jeweiligen Namen unterhalb des Eingabefeldes eingefügt werden.

[[Datei:JasperReports-Handbuch_ireport_filter1.png]]

Zu den Feldern und Variablen gibt es auch noch Funktionen in dem 3. unterem Kästchen.

Ein Beispiel für Textausgabe:

Es soll ausgegeben werden „Auswertungszeitraum 1.1.<<Jahr>> bis 31.12.<<Jahr>>“.

Anstatt zwei statische Textfelder und zwei dynamische zu machen, legt man eine Expression an:

"Auswertungszeitraum: 1.1."+$F{legende_Jahr_value}+" bis 31.12."+$F{legende_Jahr_value}

<blockquote>Der Clou an JasperReports ist: da das Programm auf der Programmiersprache Java beruht, kann man in Expressions echten Java Code einfügen bzw. um eigenen Java Code erweitern. Wenn Sie z.B. wissen dass das benutzte Feld "$F{Lehr- und Forschungsbereich}" vom Typ String ist, können Sie alle in Java eingebauten String Funktionen benutzen, z. B. Substring, contains, indexOf, toLowerCase etc. Analog auch für andere Datentypen.
</blockquote>

=== Bedingungen ===

Bedingungen sind in dem Expression Editor auch möglich. Wenn z.B. eine Variable nur Ausgegeben werden soll, wenn der Wert größer, kleiner oder gleich einem anderem vorgegebenen Wert oder Variable sein soll, wird folgende Syntax verwendet:

<<Bedingung>> ? <<Ausgabe wenn Bedingung wahr>> : <<Ausgabe wenn Bedingung falsch>>

Bedingungen:

String1 == String2

String1 != String2

Nummer1 > Nummer2

String1.contains( String2 )

String1 == null

usw.

Wie oben angegeben: Wenn die Bedingung wahr ist, wird der Wert nach dem Fragezeichen genommen. Wenn die Bedingung falsch ist, wird der Wert nach dem Doppelpunkt genommen.


=== Umgang mit Zeichenketten ===

Häufig werden für Berichtsausgaben Zeichenketten manipuliert. Dadurch, daß JasperReports innerhalb der Java-Runtime läuft, stehen uns mächtige Methodenaufrufe zur Verfügung, die in Java schon eingebaut sind.

Für Zeichenketten hier eine Übersicht:

http://docs.oracle.com/javase/7/docs/api/java/lang/String.html


=== Umgang mit Datumsfeldern ===


==== Datumswerte aggregieren ====

Fürs Berichtsdesign auf aggregierter Ebene ist es oft praktisch, Datumswerte auf "grobere" Kategorien zu aggregieren, z.B. Monate, Quartale, oder Jahre. Um solche Werte auszugeben bzw. danach zu gruppieren können Sie eigene Variablen anlegen, die dann im Expression Editor mit Hilfe von Java berechnet werden. Hier ein Beispiel für eine Transformation vom Datum zur Einheit "Jahr-Monat":

(($F{Datum}.getYear()+1900)*100)+($F{Datum}.getMonth()+1)

Wenn wir annehmen, dass im Feld "Datum" ein Datums- oder Zeitstempel-Wert steht, dann wird über die o.g. Expression daraus ein Zahlenwert nach dem Muster Jahr (vierstellig) + Monat (zweistellig), z.B. für den 13.5.2013 würde daraus der Wert 201305. Nach diesem ganzzahligen Wert kann man dann sortieren und gruppieren.

<blockquote>Anmerkung: die o.g. Methoden getYear() und getMonth() sind seit einigen Jahren in Java "deprecated", d.h. sie könnten in zukünftigen Java Versionen entfallen. Aber da dies in den letzten 7 Jahren nicht passiert ist, können wir damit noch arbeiten und optimistisch sein. Falls die Methoden wirklich entfernt werden, muss man eigene statische Methoden mit dem in Java eingebauten Calender-Objekt erstellen, Codebeispiele dazu gibt es viele im WWW.
</blockquote>

wenn man Text "Erzeugungsdatum" und das Datum in einem Feld haben will geht so: 
"Erzeugungsdatum:"+new SimpleDateFormat("dd.MM.YYYY", Locale.GERMAN).format(new java.util.Date())


==== Zeichenketten zum Datumstyp konvertieren ====

Wenn Sie ein Datum als String-Feld geliefert bekommen, können Sie es mit Groovy zum Typen "java.util.Date" konvertieren, z.B. um danach zu sortieren. Wenn z.B. das Feld „Beginn“ den Typ String hat und gefüllt ist mit dem Wert "18.11.2020 18:05:00", dann können Sie eine Variable vom Typ java.util.Date erzeugen, mit der Expression:

Date.parse("dd.MM.yyyy hh:mm:ss", $F{Beginn})


=== Besonderheiten / Workarounds ===

* Bei Feldern mit Länge 1 klappte einfaches equals nicht, mit einer substring Anweisung geht es dann:

$F{legende_Art des Berichts_value}.substring(0,1).equals("B")

* Folgejahr berechnen: Selbst es das Feld Jahr gibt und es als Integer definiert ist in der Felderinfo, klappt der Bericht nur in JasperReports nicht in SuperX nicht wenn man schreibt: 
$F{legende_Jahr_value}.intValue()+1 
geht nicht, statt dessen: 
new Integer($F{legende_Jahr_value}).intValue()+1
* Statt das Element table zu nutzen kann man auch manuell eine Tabelle erzeugen, in dem man per Rechtsklick auf ein Element Padding und Borders bearbeitet. Siehe http://www.youtube.com/watch?v=LbU6qTj3zQM
* Achten muss man dann darauf, dass Felder die Null sein können nicht „remove when blank“ haben und als TextFieldExpression besser nehmen: $F{Betrag}==null?" ":$F{Betrag}
* außerdem, wenn die erste Spalte einen stretch with overflow hat auch bei „stretch type“ „relative to tallest object“ einstellen
* Zeilenumbruch in Feld 
Markup auf html setzen und dann z.B. "Plan'''''' ''''''"+$F{legende_Jahr_value}


=== Häufig benötigte Transformationen ===


==== Umrechnung Semester-tid in Namen ====

$V{Semester (Schlüssel)}.toString().endsWith("1")?("SS "+$V{Semester (Schlüssel)}.toString().substring(0,4)):("WS "+$V{Semester (Schlüssel)}.toString().substring(0,4)+"/"+(new Integer($V{Semester (Schlüssel)}.toString().substring(0,4))+1).toString())


==== Umrechnung Semester in akad. Jahr ====

Die folgende Formel formt die Semesterzahl aus dem Studierenden-Datenblatt in ein akad. Jahr um nach der Formel "Akad. Jahr=WS + darauf folgendes SS", z.B. WS 2009/2010 und SS 2010 werden zum akad. Jahr 2009:

$F{Semester der Belegung (Schlüssel)}.toString().endsWith("2") ? $F{Semester der Belegung (Schlüssel)}.toString().substring(0,4):(new Integer($F{Semester der Belegung (Schlüssel)}.toString().substring(0,4))-1).toString()

Die Formel nimmt beim WS die ersten vier Stellen des Semester-Schlüssels, und beim SS werden die ersten vier Stellen als Ganzzahl codiert, und dann wird 1 subtrahiert.

Da es diverse Definitionen von Akad. Jahr / Studienjahr / Prüfungsjahr gibt, kann man das obige Beispiel leicht für eigene Bedürfnisse abwandeln.


== Pattern Expression ==

Die Formatierung der Werte kann mit Hilfe des Attributes "Pattern" gesetzt

werden. Hat man allerdings unterschiedliche Werte z.B. Datumsangaben und Währungseinheiten

oder Ganzzahlen und Kommazahlen und möchte diese unterschiedlich formatieren, so kann dies

mit dem Attribut "Pattern Expression" dargestellt werden.

Hier ein Beispiel für die Ausgabe von Ganzahlen und Kommazahlen:

$V{valueMeasure}.doubleValue() == Math.floor($V{valueMeasure}.doubleValue()) &&

!Double.isInfinite($V{valueMeasure}.doubleValue()) ?

"#0;#0" : "###0.00;###0,00"

Hier der Pattern Expression Editor:

[[Datei:JasperReports-Handbuch_ireport_pattern_expression_editor.png]]

Hier das Ergebnis:

[[Datei:JasperReports-Handbuch_ireport_pattern_expression_ergebnis.png]]


== Fortgeschrittene Techniken bei Feldern ==

Textfelder enthalten standardmäßig nur den Feldnamen, aber die zugrunde liegenden [[#2.9.Expression Editor|outline|Ausdrücke]] lassen sich erweitern. Dabei kann auch alle Java Klassen zugegriffen werden, die sich im CLASSPATH befinden, z.B. [[#2.9.2.Umgang mit Zeichenketten|outline|java.lang.String]].

Hier ist ein Beispiel, in dem die Klasse "StringBuilder" (wird mit Java ausgeliefert , java.lang.StringBuilder) genutzt wird, um einen Text auszugeben:

[[Datei:JasperReports-Handbuch_expression_stringbuilder.png]]

Im Ergebnis sieht das so aus:

[[Datei:JasperReports-Handbuch_expression_stringbuilder1.png]]

Das Beispiel verdeutlicht: Man könnte da auch de.meineKlasse.erzeugeText("mein Text") schreiben, und diese Klasse dann in den CLASSPATH bei Jasper Start legen, und voila! Durch diese Funktionalität lassen sich also beliebige Java Klassen einbinden. Das gleiche geht übrigens auch mit Groovy.


== Einrücken von Feldern ==

Das Einrücken von Feldern macht man am besten, in dem man mehrere Textfelder definiert und jeweils eine printWhenExpression auf die Ebene einbaut.

Alternativer Versuch war folgendes:

Wobei Nachteil bei sehr langen Texten, bei denen strech with overflows zur Geltung kommt, dann die zweite Zeile nicht eingerückt wird.

Das Einrücken von Felder kann man für Textfelder (Strings) machen, indem der SuperX-Bericht eine Spalte einruecken definiert, der je nach gewünschter Einrückung eine Anzahl von x enthält, also z.B.

{| class="wikitable"
|-
!
!
!
|-
| Name
| Betrag
| Einrücken
|-
| 1. Überschrift
| 30000
| X (mindestens 1 x nötig)
|-
| 1.1 Unterüberschrift
| 15000
| Xxxxx
|-
| 1.3. UnterUnterübersichrift
| 3000
| xxxxxxxxx
|}

Dann kann man ein Textfeld erzeugen und bei TextFieldExpression einfach eintragen:

$F{Einruecken}.replace('x',' ')+$F{Name}

Für Zahlfelder (z.B. Double) geht das so nicht so gut, weil dann das Pattern der Darstellung ###0,00 nicht mehr greift.

Man definiert drei Felder nebeneinander, Beispiel:

{| class="wikitable"
|-
!
!
!
|-
| $F{Name}
| ${Betrag}

PrintWhenExpression

$F{Hierarchie_Ebene}.intValue()>=6

| ${Betrag}

PrintWhenExpression

$F{Hierarchie_Ebene}.intValue()<6

|}

Bei Ebene 1-5 wird ganz rechts ausgegeben, bei Ebene >=6 wird mittig ausgegeben.


== Berechnungen ==

Bei Berechnungen muss immer auch auf (ich nenne es mal) die Gültigkeit der Variable geachtet werden. Wenn eine Variable eine Summe bildet kann diese für z.B. „jetzt“ oder für eine Gruppe oder den ganzen Report gelten. Je nach Gültigkeit gilt z.B. die Summe nur für die aktuelle Gruppe (bei Gruppenbändern).

Achtung: Es gibt nicht nur eine Gültigkeit bei der Variable selber (Reset type) sondern auch bei dem Element in dem Bericht. Wenn eine Variable in den Bericht gezogen wird, besitzt das entstandene Element eigene Eigenschaften, bei dem dann die „Evulation Time“ eingestellt werden kann.


=== Prozentrechnung ===

Für die Prozentrechnung musst zuerst eine Variable z.B. mit dem Namen "Gesamt" anlegen mit den Eigenschaften:

Calculation = Sum

Reset type = Report

Dannach kann ein Textfeld mit dem Inhalt:

$F{Summe} / $V{Gesamt}

erstellt werden mit den Eigenschaften:

Expression Class = Double

Pattern = #.##0.00 % (kannst du unter Prozent auswählen)

Evaluation Time = Auto

In der Variable „Gesamt“ wird die Summe aus allen Werten des Feldes Summe gezogen.

Bei Prozentberechnungen in Grafiken muss in manchen Fällen der Wert auf 0 überprüft werden. Das kann man z.B. mit folgendem Code machen:

( $V{zahl1} == 0 || $V{zahl2} == 0 ? 0 : ( $V{zahl1} / $V{zahl1} * 100) )

Damit ist dann sichergestellt, dass es keine Probleme bei der Berechnung gibt, auch wenn die Zahlen mal leer sind.


=== Rundung ===

Wenn man runden möchte den Datentyp am besten auf BigDecimal stellen. Ansonsten wird schon mal aus 2,45 gerundet 2,4.


== Hyperlinks ==


=== Externe Links ===

Ein Textfeld kann auch als Hyperlink befüllt und ausgegeben werden. Vorab bemerkt: Hyperlinks funktionieren in internen Viewer von JasperSoft Studio sowie beim Export nach Excel nicht bzw. nur eingeschränkt, zumindestens wenn man POI als Excel Engine nutzt. Selbst wenn Hyperlinks ausgegeben werden, ist in den Sicherheitseinstellungen von Excel oder OpenOffice eine Änderung vorzunehmen, damit Hyperlinks auch aktiv sind. Da es hier komplexte Unterschiede bei MS Excel-/OpenOffice-Versionen gibt, haben wir das Thema nicht weiter verfolgt und raten davon ab.

In den anderen üblichen Ausgabeformaten (PDF, HTML) funktionieren die Hyperlinks.

Dabei gibt es zwei Varianten:

Das Textfeld hat als Markup Typ den Wert "html", und die Hyperlinks werden in HTML-Notation eingefügt. Beispiel:

[[Datei:JasperReports-Handbuch_hyperlink_pfd3.png]]

Hier der Quellcode der textField-Expression zum Kopieren:

$V{Gross_Forsch_Proj_Sprech}.replaceAll( "\n"," " )+"<a href=\"http://www.meinserver.de/url/\">Siehe Details</a>"

Im Ergebnis sieht das dann so aus:

[[Datei:JasperReports-Handbuch_hyperlink_pfd2.png]]

Bei Variante 2 erhält ein ReportElement im Quellcode die entsprechende Eigenschaft. In der von uns genutzten Version von JasperSoft Studio (6.5.1 final) war das noch nicht im GUI bearbeitbar, daher kann man das nur im Quelltext machen. Immerhin "zerstört" JasperSoft Studio dies beim Speichern nicht.

Die Eigenschaft des textField heißt hyperlinkType="Reference" und wird wie folgt belegt:

<textField pattern="" isBlankWhenNull="true" '''hyperlinkType="Reference"'''>

<reportElement mode="Opaque" x="363" y="22" width="259" height="22" forecolor="#000000" backcolor="#FFFFFF" uuid="48c8e2df-f231-4433-8836-309668e0a859">

<printWhenExpression><![CDATA[$V{Gross_Forsch_Proj_Sprech}.length() >100]]></printWhenExpression>

</reportElement>

<box>

<pen lineWidth="0.5"/>

<topPen lineWidth="0.5"/>

<leftPen lineWidth="0.5"/>

<bottomPen lineWidth="0.5"/>

<rightPen lineWidth="0.5"/>

</box>

<textElement textAlignment="Left" verticalAlignment="Middle" rotation="None" markup="html">



<paragraph lineSpacing="Single"/>

</textElement>

<textFieldExpression><![CDATA["Siehe Details"]]></textFieldExpression>

'''<hyperlinkReferenceExpression><![CDATA["http://meinserver/url"]]></hyperlinkReferenceExpression>'''

</textField>

Am Ende des textField wird dann im Element hyperlinkReferenceExpression das Ziel des Hyperlinks definiert. Da dies eine Expression ist, kann man die Hyperlinks auch dynamisch aufbauen. In der Ausgabe dies das dann so aus:

[[Datei:JasperReports-Handbuch_hyperlink_pdf.png]]

Je nach PDF Viewer muss man auch hier in den Sicherheitseinstellungen Hyperlinks aktivieren.


=== Interne Links/Anker ===

Auf einem Text Field kann ein Link eingetragen werden. Dafür muss man einfach mit der rechten Maustaste auf das Textfeld klicken und dann auf Hyperlink klicken.

Das erste Feld oben „Anchor Name Expression“ kann einen Text enthalten, auf den von einer anderen Stelle verwiesen werden kann. Es ist also eine Markierung.

Wenn ich einen Hyperlink Type wähle, kann ich auch Verweise in den generierten Bericht erzeugen. Z.B. kann ich hier den Type „LocalAnchor“ wählen.

Um z.B. ein Inhaltsverzeichnis zu erzeigen, welches im PDF bei klick auf ein Element dort hin springen soll, gehe ich zunächst zu der Stelle an der die Sprungmarke gesetzt werden soll und erzeuge dort ein Text Field mit der „Anchor Name Expression“ z.B. „Überschrift1“. Das Inhaltsverzeichnis muss dann auch aus Text Fields erzeugt werden und dort wähle ich dann bei Hyperlink type „LocalAnchor“. Nun habe ich unter der Auswahl von dem Hyperlink type ein neues Eingabefeld „Hyperlink Anchor Expression“. Dort trage ich jetzt exakt den gleichen Text „Überschrift1“ ein und im generierten PDF kann ich dort drauf klicken um an die Markierte Stelle zu kommen.


== Berichts-Properties setzen ==

Es gibt auf Berichtsebene die Möglichkeit, die Ausgabe der Berichte über sog. "Properties" zu steuern, teilweise auch formatspezifisch. So können Sie z.B. steuern, daß bei der Ausgabe nach Excel Zahlenfelder als Zahlenfelder ausgegeben werden, nicht als Textfelder.

Um die Berichts-Properties zu setzen, können Sie dies entweder für einzelne Berichte, order auch Server-weit einstellen.

Bei einzelnen Berichten gehen Sie im Report Inspector auf das oberste Element, und dort auf "Eigenschaften".

[[Datei:JasperReports-Handbuch_report_properties1.png]]

Sie erhalten dann eine Liste der Eigenschaften:

[[Datei:JasperReports-Handbuch_report_properties2.png]]

Dort können Sie Zeilen hinzufügen, bearbeiten und löschen. Eine Erläuterung der jew. Property erhalten Sie in dem jew. Dialog.

Um eine Property systemweit zu speichern, legen Sie eine Textdatei mit dem Namen "jasperreports.properties" an, und legen diese in den CLASSPATH. Im Kontext von Tomcat ist dies das Verzeichnis webapps/superx/WEB-INF/classes.


== Seitenlayout ==


=== Seitenumbrüche ===

Es gibt drei Typen von Seitenumbrüchen:

* Wenn der gesamte Bericht paginiert ist (Report-Eigenschaft "Ignore Pagination"="false"), berechnet JR aufgrund des Seitenformats die Seitenumbrüche automatisch, und fügt auch, sofern vorhanden, die Bänder "page header" und "page footer" hinzu.
* Bei eingeschalteten Eigenschaften des jew. Bandes "Start on a new page=true" werden Seitenumbrüche ebenfalls aufgeführt
* Es gibt für manuelle Seitenumbrüche in der Palette das Element "Break", das an beliebiger Stelle einen manuellen Seitenumbruch einfügt. Nun ist die Frage: wenn gesamte Bericht nicht paginiert ist ("Ignore Pagination"="true"), was dann bei einem Break passieren soll. In älteren JR Versionen (vor 4.8) wurde der Break trotzdem gesetzt. In Versionen ab 4.8 passiert das nicht mehr, man kann aber ab Version 5.1 über die Berichts-Property 
net.sf.jasperreports.page.break.no.pagination=apply 
das alte Verhalten nachbilden.

In JasperSoft Studio oder iReport kann man zusätzlich noch beim Rendern des Berichts über den Parameter JRParameter.IS_IGNORE_PAGINATION steuern, ob Seitenumbrüche ausgeführt werden. Dies überlagert die Berichtseinstellung, wenn es angehakt ist. Das ist z.B. sinnvoll, wenn Sie im PDF Export Seitenumbrüche haben wollen, in Excel oder HTML aber nicht.

Leider kann man diesen Parameter nicht im Servlet setzen. Wenn Sie Seitenkopf/Fuß bei PDF wünschen, bei Excel aber nicht, nutzen Sie die Anleitung [[#2.21.5.Seitenkopf und Seitenfuß bei Excel unterdrücken|outline|unten]].

Es gibt verschiedene Möglichkeiten, wie sich das Detailband bei einem Seitenumbruch verhalten soll. Diese werden über den ‚Split Type‘ des Bandes gesteuert. Beispiel:

Bei einem Seitenumbruch wird die aktuelle Zeile des Detailbandes aufgeteilt und geht auf der nächsten Seite weiter. Der ‚Split Type‘ steht auf Stretch.

[[Datei:JasperReports-Handbuch_Eingebettet_011.png|642x170px]]

Falls erwünscht ist, dass jede Zeile ganz dargestellt wird, kann der ‚Split Type‘ auf Prevent gestellt werden:

[[Datei:JasperReports-Handbuch_Eingebettet_012.png|300x281px]]Das Ergebnis sieht wie folgt aus:

[[Datei:JasperReports-Handbuch_Eingebettet_013.png|642x223px]]


=== Die Höhe von Textfeldern dynamisch anpassen ===

[[Datei:JasperReports-Handbuch_layout1.png]]

Textfelder besitzen die Eigenschaft „Stretch With Overflow“. Wird diese aktiviert, passt das Textfeld dynamisch seine Größe, falls der Inhalt nicht in das Feld passt. Der Text bricht um und die Höhe des Feldes wird vergrößert. Damit auch alle anderen Felder derselben Zeile ihre Größe entsprechend anpassen wird der „Stretch Type“ aller Felder dieser Zeile auf „Relative To Tallest Object (deprecated)“ gesetzt. Die Felder passen ihre Höhe dann dem höchsten Feld dieser Zeile an. Im Detailband genügt dies. Für Bänder mit festgelegter Zeilenanzahl, wie beispielsweise dem Titelband ist eine weitere Einstellung vorzunehmen.

Um im Titelband die Funktion „Stretch With Overflow“ nutzen zu können, ist es notwendig allen Feldern in darunterliegenden Zeilen den „Position Type“ „Float“ zuzuweisen. Die Position der Felder verändedrt sich dann entsprechend der Höhe darüberliegender Felder.

[[Datei:JasperReports-Handbuch_layout2.png]]


=== Bericht ausgeben, ohne Dateninput ===

Wenn der Bericht bzw. das Layout mit Titelband etc. ausgegeben werden soll, obwohl es keine Daten gibt, dann wird die Funktion ‚When No Data Type‘ auf ‚All Sections No Detail‘ gestellt.

[[Datei:JasperReports-Handbuch_Eingebettet_014.png|336x374px]]


== Besonderheiten beim Export nach Excel ==

Für jedes Exportformat gibt es auf Berichtsebene bzw. darunter spezielle Properties, die Feinheiten des Zielformates festlegen. Dies wird im folgenden anhand des Excel-Exports von Formeln und Namen von Arbeitsblättern (Sheet-Names) gezeigt.

Bitte beachten Sie dass diese Hinweise für den "alten" Excel Export ("xls") gelten. Für die Exportformate xlsx, JExcel-API oder OpenOffice-Spreadsheets funktionieren diese teilweise nicht.

Um leere Zeilen im Excelexport zu vermeiden, im jrxml-Kopf:

<property name="net.sf.jasperreports.export.xls.collapse.row.span" value="true"/>

<property name="net.sf.jasperreports.export.xls.remove.empty.space.between.columns" value="true"/>

<property name="net.sf.jasperreports.export.xls.remove.empty.space.between.rows" value="true"/>

wenn man Zahlenanpassung möchte

<property name="net.sf.jasperreports.export.xls.auto.fit.row" value="true"/>

<property name="net.sf.jasperreports.export.xls.font.size.fix.enabled" value="true"/>

→ font wird ggfs. verkleinert

<property name="net.sf.jasperreports.print.keep.full.text" value="true"/>


=== Excel-Formeln ===

Es gibt auch die Möglichkeit Zahlen nicht nur vorab zu berechnen, sondern beim Export nach Excel als Excel-Formel zu übergeben.

Um diese Funktion zu aktivieren muss im JRXML die Property mit folgender Zeile eingefügt werden:

<property name="net.sf.jasperreports.export.xls.detect.cell.type" value="true"/>

Oder über die Report Properties:

[[Datei:JasperReports-Handbuch_excel_export_detect_cell_type1.png]]

Danach können in jedem Text Field in der Property expression:

[[Datei:JasperReports-Handbuch_excel_export_detect_cell_type2.png]]

folgende Einträge ergänzt werden:

[[Datei:JasperReports-Handbuch_excel_export_detect_cell_type3.png]]

Rechts neben net.sf.jasperreports.export.xls.formula wird die Formel für Excel eingetragen, allerdings ohne = am Anfang. Außerdem werden nicht alle Excel-Formeln unterstützt, insbesondere nicht deren deutsche Lokalisierung (z.B. oben SUMME(D119...). Details finden Sie in der [https://poi.apache.org/spreadsheet/formula.html POI]-Dokumentation. Um zu erfahren wie die Felder lauten, welche berechnet werden sollen, am besten den Bericht einmal ausführen und in Excel anzeigen lassen. Achtung: Wenn der Bericht noch bearbeitet wird, können sich die Felder noch verändern.

Bei net.sf.jasperreports.export.xls.pattern können speziell für Excel Formatangaben gemacht werden. In dem obigen Beispiel "#,##0.00;-#,##0.00" gibt es 2 Nachkommastellen und ein Tausender-Trennzeichen. Wenn z.B. Tausende von Euro angezeigt werden sollen, nimmt man als Pattern #.

<blockquote>Fallstrick: in der von uns getesteten Version (4.1.3) wurde die Property net.sf.jasperreports.export.xls.formula nur dann ausgewertet, wenn das das jew. Textfeld eine korrekte "Text field expression" hat, sie darf also nicht leer sein. Ob das ein Bug ist oder nicht ist uns derzeit unklar.
</blockquote>
Beispiel für eine komplexe Summenformel SUM(D7:D20,D28,D33,D40)

Man kann die Formel auch als Expression formulieren, z.b. um eine Division durch 0 zu verhindern. Setzen Sie dazu das Häkchen bei "Use an expression":

[[Datei:JasperReports-Handbuch_excelformula_expression.png]]

Das obige Beispiel führt die Formel "D91/D149" nur aus, wenn die Variable $V{Haush_Professoren_1} (die Quelle für die Zelle D149) einen Wert größer 0 hat. Wenn nicht, wird keine Formel reingeschrieben, sondern der Wert 0.

Diese Funktion bietet natürlich noch viel mehr Möglichkeiten, z.B. könnte man damit Excel-Zellennummern dynamisch berechnen etc. Beispiele dazu finden Sie in den JasperReport Demos in demo/samples/xlsformula/reports/XlsFormulaReport.jrxml.


==== Zeilennummern dynamisch berechnen (Ein Beispiel) ====

Will man dass in der gesamten Exceldatei immer Spalte F=D+E ist, braucht man nicht für jede Zeile feste Formeln eintragen.

Als Erstes schaut man in welcher Zeile die eigentlichen Daten anfangen, also z.B. nach den zwei Headerzeilen ganz am Anfang der Tabelle und den 3 Spaltenüberschriften, die pro Seite wiederholt werden.

Hier ein Beispiel

($F{Zweckbestimmung}.isEmpty()||($F{Soll}==null&&$F{Reste}==null))?"":"SUM(D"+(($V{PAGE_NUMBER}.intValue()*3)+$V{REPORT_COUNT}.intValue()+2)+",E"+(($V{PAGE_NUMBER}.intValue()*3)+$V{REPORT_COUNT}.intValue()+2)+")"

Elegant geht es auch so

($F{Zweckbestimmung}.isEmpty()||($F{Soll}==null&&$F{Reste}==null))?"":"INDIRECT(\"D\" & ROW())+INDIRECT(\"E\" & ROW())"

Das hat nur den Nachteil, dass die Formel in Excel nicht so schön ist.


==== WENN-/IF-Formel – '''Ein''' Fallstrick ====

Ein Fallstrick, der uns einige Stunden Arbeitzeit gekostet hat: die IF-Formel wird in OpenOffice und MS Excel mit dem Trennzeichen ";" für die THEN- und ELSE-Bedingung formuliert. JasperReports nutzt als Trennzeichen aber ",". Interessanterweise wird dann im fertigen Excel das "," als ";" angezeigt.


==== SUMIF – Summen mit Bedingungen (Bsp.: Zwischensummen ignorieren) ====

Wenn die Summe über einen großen Bereich gezogen werden soll, in dem auch Zwischensummen vorkommen, gibt es die Folgende Formel:

SUMIF(A"+$V{zeile_start}.intValue()+":A"+$V{zeile_ende}.intValue()+",\"<>Summe*\",B"+$V{zeile_start}.intValue()+":B"+$V{zeile_ende}.intValue()+")

Wenn die Zwischensummen mit addiert werden würden, wäre das Ergebnis doppelt so hoch wie es sein sollte. Die Funktion SUMIF beinhaltet 3 Bereiche. Zuerst wird der Bereich eingegeben, auf den die Bedingung angewendet wird:

A"+$V{zeile_start}.intValue()+":A"+$V{zeile_ende}.intValue()+"

Hier ist das z.B. von A1 bis A10.

Danach kommt die Bedingung:

\"<>Summe*\"

Das bedeutet, es werden alle Zeilen genommen, die '''''NICHT''''' mit „Summe“ anfangen.

Als letztes kommt der Bereich, der summiert werden soll:

B"+$V{zeile_start}.intValue()+":B"+$V{zeile_ende}.intValue()+"

Hier ist das z.B. von B1 bis B10.

In diesem Beispiel werden alle Zahlen zwischen B1 und B10 aufsummiert, wenn in der entsprechenden Zeile in der Spalte A der Text nicht mit „Summe“ beginnt.


==== Statt 0-Werten eine leere Zelle ausgeben ====

Im Standardfall wird eine 0 ausgegeben, falls eine Formel in Excel auf leere Zellen oder Zellen mit einer 0 verweist. Um stattdessen eine leere Zelle auszugeben wird die Property Property net.sf.jasperreports.export.xls.pattern genutzt. Das obige Beispiel wird erweitert:

###0.00;-###0.00;;@

Die jeweiligen Zellen weisen nun 2 Nachkommastellen aus und zudem werden 0-Werte nicht mehr angezeigt.


==== OpenOffice vs Excel ====

OpenOffice kommt mit folgender Berechnung klar

"INDIRECT(\"E\" & ROW())+INDIRECT(\"F\" & ROW())-INDIRECT(\"G\" & ROW())-INDIRECT(\"H\" & ROW())":""

Excel macht hier Ärger, wenn eine der Zellen Null ist, wird als Gesamtergebnis #WERT angezeigt, entweder Sum-Formel benutzen, oder noch mal mit IF prüfen, ob Zelle gefüllt ist

Struktur ist (IF(Zelle leer,0,sonst Zellenwert))

"IF(INDIRECT(\"E\" & ROW())=\"\",0,INDIRECT(\"E\" & ROW()))+IF(INDIRECT(\"F\" & ROW())=\"\",0,INDIRECT(\"F\" & ROW()))-IF(INDIRECT(\"G\" & ROW())=\"\",0,INDIRECT(\"G\" & ROW()))-IF(INDIRECT(\"H\" & ROW())=\"\",0,INDIRECT(\"H\" & ROW()))":""


=== ‚Stretch with Overflow‘ in Excel korrekt verarbeiten ===

Wenn Sie eine Zelle haben mit besonders langem Text, z.B. „Unterstützungen auf Grund der Unterstützungsgrundsätze, Fürsorgemaßnahmen sowie Kosten nach dem Arbeitssicherheitsgesetz“, hilft es, nur bei der Zelle, Line Spacing auf double zu setzen, dann sieht es in Excel besser aus.

Es wird das Stretch richtig verarbeitet.

<property name="net.sf.jasperreports.export.xls.auto.fit.row" value="true"/>

<property name="net.sf.jasperreports.export.xls.font.size.fix.enabled" value="true"/>

→ verkleinert fonts bei bedarf

<property name="net.sf.jasperreports.print.keep.full.text" value="true"/>


=== Pagination in Excel-Dokumenten ===

In Excel-Dokumenten in die Seitengröße naturgemäß irrelevant. Trotzdem wird das im jrxml gesetzte Seitenformat beim Excel-Export beachtet. Das stellt sich so dar, dass im Excel-Dokument der „Rest der Seite“ durch einzelne breitere beziehungsweise höhere Zellen gefüllt wird. Das sieht beispielsweise folgendermaßen aus:

[[Datei:JasperReports-Handbuch_excel_export_pagination1.png]]

Unter dem Tabellenschluss ist die Zeile 84 so hoch, dass die im jrxml eingestellte Seitenhöhe erreicht ist. Um das zu verhindern wird für den gesamten Bericht isIgnorePagination=“true“ gesetzt. Die Einstellung wird im source-Code ganz oben im Tag <jasperReport isIgnorePagination=“true“> gesetzt oder über die grafische Oberfläche:

[[Datei:JasperReports-Handbuch_excel_export_pagination2.png]]


=== Excel-Export in einzelne Tabellenblätter ===

Normalerweise werden beim Export nach Excel die Berichtsinhalte in das erste Tabellenblatt geschrieben. Je nachdem wie Sie auf Berichtsebene die Property net.sf.jasperreports.export.xls.one.page.per.sheet setzen, wird der Seitenumbruch gesteuert. Setzen Sie den Wert auf "true", dann führt jeder Seitenumbruch zu einem neuen Sheet bzw. Arbeitsblatt in der Excel-Datei. Standardmäßig werden diese dann "Page 1", Page 2" etc. benannt.

Wenn Sie die Namen der Sheets explizit vergeben wollen, können Sie dies wie folgt machen: Wenn Sie z.B. die Berichtsproperty net.sf.jasperreports.export.xls.sheet.names.all auf den Wert

"Hauptseite/wichtige Seite/Unwichtige Seite" setzen, bekommen Sie drei Sheets mit den jew. Namen, d.h. der "/" fungiert als Trennzeichen. Dementsprechend sollte im Namen des Sheets kein "/" auftauchen.

Seit JR 4.1 gibt es auch die Möglichkeit, die Sheetnamen dynamisch zu vergeben. Auch hier werden Properties mit Expressions genutzt.

Es gibt verschiedene Möglichkeiten Berichtsinhalte in verschiedene Excel-Tabellenblätter zu verteilen. Im Folgenden werden zunächst Möglichkeiten betrachtet, welche bei Einzelberichten in Frage kommen. Danach geht es um die klassische Haupt- und Unterberichtsstruktur und zuletzt um Booklets, welche die in den meisten Fällen wohl elegantere Alternative zu klassichen Haupt- und Unterberichten darstellen.


==== Einzelne Berichte ====

Nehmen wir an wir haben einen Bericht mit der Gruppierung auf die Spalte "LFB", im Gruppenkopf befindet sich ein Text Field mit der Expression $F{LFB}.

Sie können diesem Textfeld eine Property net.sf.jasperreports.export.xls.sheet.name geben:

[[Datei:JasperReports-Handbuch_excel_export_sheets_names.png]]

Das Textfeld erhält somit beim Füllen des Berichts den jew. Wert, z.B. "Anglistik, Amerikanistik", und diese Überschrift steht auch im Gruppenkopf. Wenn der Gruppenkopf das Attribut "Start on a new page" hat, dann beginnt der Gruppenkopf auf einer neuen Seite und, dank der Berichts-Property net.sf.jasperreports.export.xls.one.page.per.sheet , erzeugt Excel / OpenOffice dann ein neues Sheet mit dem Namen Anglistik, Amerikanistik. Beim Sheetnamen soll nur sichergestellt werden, dass kein "/" im Text vorkommt, daher der replace-Befehl zur Sicherheit. Hier ein Screenshot in OpenOffice:

[[Datei:JasperReports-Handbuch_excel_export_sheets_names2.png]]

Man kann das gesamte Verhalten auch deaktivieren, indem man auf Berichtsebene das Attribut "Ignore Pagination" auf "true" setzen. In diesem Falle werden alle Seitenumbrüche ignoriert.

<blockquote>Hinweis für SuperX/Edustore Nutzer: leider haben wir in älteren Kernmodul-Versionen dieses Attribut " Ignore Pagination" im Servlet fest auf "true" gesetzt, so dass Sie diese Funktion im Servlet erst ab Version SuperX 4.5 bzw. HISinOne-BI 7.0 nutzen können.
</blockquote>

==== Haupt- und Unterberichte ====

Das vorherige Kapitel hat aufgezeigt, wie innerhalb eines einzelnen Einzelberichtes mit gezieltem setzen von Seitenumbrüchen ein solcher Berichte auf verschiedene Tabellenblätter eines Excel-Dokumentes augeteilt wird.

Um mehrere Einzelberichte in einem Excel-Dokument gesondert auf verschiedene Tabellenblätter aufzuteilen eignen sich klassiche Haupt- und Unterberichtsstrukturen (vgl. Kapitel 3.5). Die simpelste Methode wäre das Seitenlayout eines Berichtes so groß zu wählen, dass der gesamte Bericht auf eine Seite passt.

Falls Haupt- und Unterberichte verwendet werden, darauf achten, dass der Hauptbericht direkt unter dem letzten Unterberichtselement endet. Ansonsten entsteht ein weiteres leeres Tabellenblatt. Der folgende Screenshot zeigt, wie es nicht sein sollte. Hier muss das Summary-Band verkleinert werden, sodass es mit dem Unterberichtselement endet.

[[Datei:JasperReports-Handbuch_excel_export_main-_subreport.png]]


==== '''Individuelle Gestaltung''' bei Booklets ====

Booklets bieten diverse Vorteile beim Gestalten der einzelnen Seiten beziehungsweise Sheets. Denn jeder Unterbericht kann hier individuell formatiert werden. Dies betrifft beispielsweise die Definition von Sheetnamen, da hierfür die Eigenschaft "Tab name expression" im "Buch"-[[#2.8.1.Hauptbericht im Booklet|outline|Bericht]] vorgesehen ist. Auch das Problem, dass ein Sheet in diesem Falle nicht mehrere Seite umfassen darf (und man somit die Seitengröße unrealistisch groß machen muss) ist damit behoben.

Eine Ausnahme stellen jedoch die Properties dar. Diese werden im Hauptbericht gesetzt und gelten für alle Unterberichte.


=== Das Drucklayout in Excel konfigurieren ===


==== '''Seitenränder und Kopfzeile im Drucklayout formatieren''' ====

Zum Anlegen eines Textes in der Kopfzeile gibt es die Properties

<property name="net.sf.jasperreports.export.xls.sheet.header.center">

<property name="net.sf.jasperreports.export.xls.sheet.header.right">

<property name="net.sf.jasperreports.export.xls.sheet.header.left">

Je nach gewünschter Position wird der jeweiligen Property ein Wert übergeben. Ein Beispiel:

<property name="net.sf.jasperreports.export.xls.sheet.header.center">

<![CDATA[&"Liberation Sans,Bold"&10Meldung der Ist-Besetzung]]>

</property>

<property name="net.sf.jasperreports.export.xls.sheet.header.right">

<![CDATA[&"Liberation Sans,Bold"&10Anlage 1 &"Liberation Sans,Regular"&10 (zu VwV HWiF 3.2.1)]]>

</property>

In diesem Beispiel wird zentral der Text „'''Meldung der Ist-Besetzung'''“ übergeben. Der Text ist in der Schriftart Liberation Sans und fettgedruckt formatiert (&"Liberation Sans,Bold"), sowie in Schriftgröße 10 (&10).

Rechts wird der Text „'''Anlage 1 '''(zu VwV HwiF 3.2.1)“ verwandt. Der erste Teile „'''Anlage 1'''“ ist wie der zentrale Text formatiert (&"Liberation Sans,Bold"&10). Für den zweiten Teil „(zu VwV HwiF 3.2.1)“ wird von Fett- auf Regulärdruck gewechselt (&"Liberation Sans,Regular"&10). Weitere Möglichkeiten zur Formatierung finden sich auf https://poi.apache.org/apidocs/dev/org/apache/poi/xssf/usermodel/extensions/XSSFHeaderFooter.html.

Damit die Kopfzeile im Drucklayout sichtbar ist, ist es notwendig den Seitenrand groß genug zu gestalten. Dafür werden folgende Properties genutzt:

<property name="net.sf.jasperreports.export.xls.print.page.left.margin" value="20"/>

<property name="net.sf.jasperreports.export.xls.print.page.right.margin" value="20"/>

<property name="net.sf.jasperreports.export.xls.print.page.top.margin" value="40"/>

<property name="net.sf.jasperreports.export.xls.print.page.bottom.margin" value="10"/>



==== Vordefinierte Zeilen im Drucklayout auf jeder Seite wiederholen ====

Um im Drucklayout beispielsweise einen Tabellenkopf auf jeder Seite zu wiederholen, wird die Property

<property name="net.sf.jasperreports.export.xls.sx_repeating.rows.range" value="3:7"/>

genutzt (dafür eigene Klasse de.superx.servlet.SxJRXlsExporter geschaffen und de.superx.servlet.JasperCreator angepasst – aktuell in NHS-Pack für 7.1 enthalten). Der Wert gibt an, welche Zeilen des Excel-Dokumentes im Drucklayout auf jeder Seite wiederholt werden. Im Beispiel (''value="3:7"'') sind die Zeilen 3 bis 7 betroffen.


==== Seitenumbrüche im Drucklayout verhindern ====

Teilweise ist es wünschenswert Seitenumbrüche im Drucklayout zu verhindern, sowohl in der Breite als auch in der Höhe. Hierfür werden die Properties

<property name="net.sf.jasperreports.export.xls.fit.width" value="1"/>

<property name="net.sf.jasperreports.export.xls.fit.height" value="1"/>

genutzt. Also value kommen hier 1 und 0 für entweder true oder false infrage. Setzt man der Wert true, dann wird nicht umgebrochen. Das bedeutet für dieses Beispiel, dass der gesamte Inhalt des Excel-Dokuments auf eine Seite gedruckt würde.


=== Zellen verbinden ===

<property name="net.sf.jasperreports.export.xls.export.xls.sx_cell_merge" value="0,6,0,7|1,2,3,4"/>

1,1,4,1 - will merge from B2 to E2. Remember it is zero based indexing.


=== Zellschutz aktivieren ===

<property name="net.sf.jasperreports.export.xls.password" value="gmmmyflb"/>

→ Alle Zellen sind mit Passwort geschützt.

Wenn bestimmte Spalten/Zeilen nicht geschützt sein sollen:

Property net.sf.jasperreports.export.xls.cell.locked false.

Dies kann man auch über eine komplexe PropertyExpression steuern, z.B.
<source lang="sql">

(

($F{Zeile}!=null&&(

$F{Zeile}.indexOf("A")>-1||

$F{Zeile}.indexOf("B")>-1||

$F{Zeile}.indexOf("C")>-1||

$F{Zeile}.equals("I.")||

$F{Zeile}.equals("II.")||

$F{Zeile}.equals("III.")||

$F{Zeile}.equals("IV.")||

$F{Zeile}.equals("V.")||

$F{Zeile}.equals("VI.")||

$F{Zeile}.equals("VII.")||

$F{Zeile}.equals("VIII.")))||

($F{Kontengruppe}!=null&&$F{Kontengruppe}.equals("53,54,58"))||

($F{Name}!=null&&(

$F{Name}.startsWith("= Summe der (ordentlichen")||

$F{Name}.startsWith("Ordentliche ")||

$F{Name}.startsWith("- ordentliche")||

$F{Name}.startsWith("+/- Finanz")||

$F{Name}.startsWith("Summe Investitionen")||

$F{Name}.startsWith("Summe Finanzbedarf")||

$F{Name}.startsWith("Summe Deckung")||

$F{Name}.startsWith("5.1 E")||

$F{Name}.startsWith("Summe sonstige betriebl")||

$F{Name}.startsWith("Sonstige betriebliche")||

$F{Name}.startsWith("5.1.) Erträge aus Zuweisungen")||

$F{Name}.startsWith("Materialaufwand")||

$F{Name}.startsWith("= Summe Materialaufwand")||

$F{Name}.startsWith("Personalaufwand")||

$F{Name}.startsWith("= Summe Personalaufwand")||

$F{Name}.startsWith("Sonstige betriebliche Aufwendungen")||

$F{Name}.startsWith("= Summe sonstige betriebliche Aufwendungen")

)

))?"true":"false"
</source>



=== Zellen fixieren ===

In Jaspersoft Studio können Sie festlegen, dass beim Excel-Export bestimmte Zeilen und Spalten fixiert werden, indem Sie spezielle Eigenschaften für den Export konfigurieren.

Um Zeilen und Spalten in Excel zu fixieren, müssen Sie die Eigenschaften

''net.sf.jasperreports.export.xls.freeze.row ''

und

''net.sf.jasperreports.export.xls.freeze.column''

konfigurieren.

Wenn Sie möchten, dass die erste Zeile und die erste Spalte fixiert werden:

* ''net.sf.jasperreports.export.xls.freeze.row = 2''
* ''net.sf.jasperreports.export.xls.freeze.column = B''

Nach dem Export werden in Excel die erste Zeile und die erste Spalte fixiert, und der Rest des Arbeitsblatts bleibt scrollbar.

''<property name="net.sf.jasperreports.export.xls.freeze.column" value="B"/>''

<property name="net.sf.jasperreports.export.xls.freeze.row" value="2"/>


=== Hintergrund- oder Textfarben beim Excel-Export ===

Beim Excel Export werden Zellen, die ein Rechteck mit einer Print-When-Expression zugewiesen bekommen haben, u.U. nicht richtig wiedergegeben, während es beim PDF Export klappt. Um dies zu beheben müssen Sie

1. den Farbraum beim Excel Export erweitern: Excel unterstützt bei Hintergrund- oder Vordergrundfarben nur wenige [http://dmcritchie.mvps.org/excel/colors.htm Farbcodes]. Für spezielle Farben nach RGB-Wert muss die Berichts-property

<property name="net.sf.jasperreports.export.xls.create.custom.palette" value="true"/>

gesetzet werden (benötigt Bibliothek org-netbeans-core.jar im Classpath der Anwendung)

2. Statt farbiger Textfelder oder Rechtecke mit "Print-When-Expression" müssen Sie [[#2.11.Conditional styles - Zeilen fett machen|outline|Conditional Styles]] nutzen.

3. Wenn Sie mit Hintergrundfarben arbeiten, müssen die Textfelder und die jew. Styles die Eigenschaft "Opaque"="true" haben.

4. Beim Export nach Excel müssen Sie das JExcelApi nutzen. Dies ist bei SuperX seit Kernmodul 4.5 der Standard, bei HISinOne-BI seit Version 7.1.


=== Seitenkopf und Seitenfuß bei Excel unterdrücken ===

Wenn Ihr Bericht normalerweise ein Band "Page Header" bzw. "Page Footer" hat, können Sie dies beim Exportformat XLS unterdrücken (z.B. wenn Sie dort keine Seitenzahlen wünschen, bei PDF aber schon).

Setzen Sie dazu die Berichts-Property

<property name="net.sf.jasperreports.export.xls.exclude.origin.band.1" value="pageHeader"/>

<property name="net.sf.jasperreports.export.xls.exclude.origin.band.2" value="pageFooter"/>

Beim Ausgabeformat XLSX heißen die Properties:

<property name="net.sf.jasperreports.export.xlsx.exclude.origin.band.1" value="pageHeader"/>

<property name="net.sf.jasperreports.export.xlsx.exclude.origin.band.2" value="pageFooter"/>

Dies klappt ab JR Version 4.5, sie können diese Properties aber lediglich im XML-Quellcode hinzufügen.


== Dimension Tausend-Euro ==

In Excel als Dimension Tausend-Euro ausgeben, mit zwei Nachkommastellen

In Deutschem Excel bei manueller Angabe benutzerdefiniertes Format #.##0,00.

In Jasper muss Amerikanische Vorlage sein:

-> #,##0.00

Bei Excel kann man als Property Expresion net.sf.jasperreports.export.xls.pattern z.B. nehmen

#, → zeigt nur Tausender Werte an

#,##0.00, → zeigt Tausernder Werte, mit zwei Nachkommastellen an

der Werte selber ist einfach $F{Soll}

Bei PDF/HTML muss man den Wert duch 1000 teilen $F{Soll}.doubleValue()/1000

und dann als Pattern z.B. #,##0.00;-#,##0.00

Die Rundung macht das Pattern.


= Nutzung in Edustore =


== Berichtsentwicklung bei Grunddaten und Basisberichten ==


=== Allgemein ===

In den Grunddaten- und Basisberichten kann man beliebige Ergebnistabellen lokal als XML speichern, und dann als Datenquelle in JasperReports einbinden. Dann kann man den Bericht lokal gestalten, und, wenn er fertig ist, in die Weboberfläche einhängen. Die XML Datei wird nur für die Testausgabe bei JasperReports verwendet und dient als Ersatz der Datenbank. Wenn der Bericht in der Weboberfläche eingehängt ist, wird dieser direkt mit frischen Daten versorgt.

Für die Folgenden 2 Punkte „Datenquelle erzeugen“ und „Template erzeugen“ gibt es [http://www.superx-projekt.de/doku/benutzerhandbuch/movies/jasper_erzeugen.viewlet/jasper_erzeugen_viewlet_swf.html hier] einen Kurzfilm.

[[Datei:JasperReports-Handbuch_vergleich_jrxml_xml_zusammen.png]]


=== Datenquelle erzeugen ===

Wenn die Ergebnistabelle eines Berichtes vorliegt, erhält man über den XML Export von SuperX die Datenquelle für den Jasper Report.

[[Datei:JasperReports-Handbuch_iReport-Datasource_erstellen.jpg]]

Diese Datei speichert man lokal ab: Wenn das Ergebnis im Browser geöffnet wurde muss man sich den Quelltext der Seite anzeigen lassen, den Quelltext komplett markieren und kopieren ( Tastenkombination Strg + a und dann Strg + c), in einen UTF-8-fähigen Texteditor einfügen (Strg + v) und dann als eine xml-Datei abspeichern.

Falls der Tomcat in ISO Kodierung läuft, muss für JasperReports in der ersten Zeile bei encoding ein UTF-8 eingetragen werden.

Beispiel:

<?xml version="1.0" encoding="ISO-8859-1"?>

wird ersetzt mit:

<?xml version="1.0" encoding="UTF-8"?>

In JasperReports sind dann folgende Schritte zu tun, um die neue Datenquelle einzubinden.


==== Datenquelle in JasperSoft Studio ====

Die Datenquellen heißen hier "Data Adapters" und werden im Repository hinzugefügt:

[[Datei:JasperReports-Handbuch_jaspersoft_datasource1.png]]

<blockquote>Achtung: wenn Sie JasperSoft in Ihrem vorhandenen Eclipse als Plugin installiert haben, sehen Sie den Reiter "Repository" nicht; in diesem Fall liegen die Data Adapter im jew. Projekt.
</blockquote>
Im Assistenten geben Sie XML-Document als Datentyp an, und im nächsten Reiter spezifizieren Sie das Format:

[[Datei:JasperReports-Handbuch_jaspersoft_datasource2.png]]

Das Datumsformat ist bei Edustore das deutsche Schema "dd.MM.yyyy", und das Zahlenformat ist eine Zahl mit 6 Nachkommastellen und "." als Dezimaltrenner, also "#0.######". Bei Locale müssen Sie "Englisch" angeben, weil Dezimalzahlen in den Edustore-XML-Quellen den "." als Dezimaltrenner haben.

Wichtig ist auch das Ankreuzfeld "Use the report Xpath expression", dies müssen Sie immer ankreuzen.


==== Datenquelle in iReport ====

Klick auf „Report Datasources“. Es öffnet sich ein Fenster, in dem die vorhandenen Datenquellen angezeigt werden.

[[Datei:JasperReports-Handbuch_iReport-Datasource_1.jpg]]

In diesem Fenster Klickt man auf „New“ um eine neue Datenquelle anzulegen.

[[Datei:JasperReports-Handbuch_iReport-Datasource_2.jpg]]

Nun wählt man „XML file datasource“ aus und klickt auf „Weiter“.

[[Datei:JasperReports-Handbuch_iReport-Datasource_3.jpg]]

Im letzten Schritt wählt man einen Eindeutigen Namen aus, der auch später in dem Dropdown Menü erscheint, gibt den Dateipfad an und ändert die restlichen Einstellungen wie im Screenshot.

[[Datei:JasperReports-Handbuch_iReport-Datasource_4.jpg]]

Die Formate für Datum und Nummer müssen angegeben werden, da sonst die amerikanischen angenommen werden. Bei Locale müssen Sie "Englisch" angeben, weil Dezimalzahlen in den Edustore-XML-Quellen den "." als Dezimaltrenner haben.

<blockquote>Hinweis: in JasperReports 3.7.1 werden trotz des korrekten Zahlenformats die Dezimalstellen von Beträgen immer mit ",00" wiedergegeben. Dies liegt an der "Locale", man muss diese auf "Englisch" umstellen. Das Problem ist allerdings: sobald man das macht, kann man die XML-Datenquelle in der Datenquellenverwaltung nicht mehr ändern, d.h. man muss sie bei Änderungen löschen und neu einfügen.
</blockquote>
Nach dem Speichern erscheint die Datenquelle im dropdown Menü und kann ausgewählt werden. Damit man die Datenquelle nutzen kann, braucht man auch noch ein Template.


=== Template erzeugen ===

Um ein leeres Template zu erzeugen, geht man wieder in die Ergebnistabelle der selben Maske, deren Datenquelle erstellt wurde, wählt im Dropdown Menü neben „Bericht entwerfen“ „Leerer Bericht“ aus und klickt auf das Icon daneben „Export als JasperReport-Template“.

[[Datei:JasperReports-Handbuch_iReport-leeren_Bericht_erstellen.jpg]]

Diese Datei speichert man Lokal ab. Wenn das Ergebnis im Browser geöffnet wurde muss man sich den Quelltext der Seite anzeigen lassen, den Quelltext komplett markieren und kopieren ( Tastenkombination Strg + a und dann Strg + c), in einen UTF-8-fähigen Texteditor einfügen (Strg + v) und dann als eine jrxml Datei abspeichern. JR in der Endung jrxml steht für JasperReports. Damit können die Datenquellen und die Templates unterschieden werden und sogar den selben Dateinamen tragen (nur unterschiedliche Dateiendung).

Sie sollten es sich nicht zumuten und versuchen über JasperReports einen neuen Bericht zu entwerfen. Nehmen Sie immer den "leeren" Bericht aus der entsprechende Maske, da dort sehr viele Kleinigkeiten voreingestellt sind. Sie sparen sich damit immens viel Arbeit.


=== Template einbinden ===


==== Reportdesign verlinken ====

Um das erstellte Template einzubinden, muss zunächst die jrxml Datei in das Verzeichnis webapps/superx/WEB-INF/reports kopiert werden. Danach muss das Stylesheet im System bekannt gegeben werden. In Grunddaten und Basisberichte geht man dazu in „Administration“ → „Masken“ → „Stylesheet suchen“ und schickt die Maske so ab. Danach klickt man bei einem beliebigen Stylesheet auf den „bearbeiten“ Button ganz rechts in der Tabelle.

[[Datei:JasperReports-Handbuch_iReport-Stylesheet_1.jpg]]

Klickt dann auf „Neuen Datensatz erzeugen“.

[[Datei:JasperReports-Handbuch_iReport-Stylesheet_2.jpg]]

In Dateiname kommt der Dateiname der jrxml Datei rein, welche sich in dem reports Ordner befindet. Beschriftung und Beschreibung sollte eindeutig dem Stylesheet zuzuordnen sein. Für JasperReport wählt man bei „Tabelle oder Maske“ „Stylesheet für eine Ergebnistabelle“ aus. Der Dateityp stellt das default Ausgabeformat fest.

Um dieses Stylesheet nun einer Maske zuzuordnen, geht man in die Maske „Administration“ → „Masken“ → „Maske suchen“, sucht in dem Feld „Maske“ die gewünschte Maske aus und klickt dann auf „Abschicken“. Nun klickt man auf den Button Stylesheets neben der Maske, der das neue Stylesheet zugeordnet werden soll.

[[Datei:JasperReports-Handbuch_iReport-Stylesheet_3.jpg]]

In dem neuen Fenster wählt man das neu erstellte Stylesheet aus und speichert diese Einstellung ab.

[[Datei:JasperReports-Handbuch_iReport-Stylesheet_4.jpg]]

Damit ist der Bericht der Maske zugeordnet.

<blockquote>Normal wird im Servlet direkt vom Berichtsergebnis nach JasperReports übergeben, d.h. ohne den Zwischenweg XML. Wenn aber im Dateinamen *_xmlsource.jrxml steht, wird Datenquelle XML erzwungen (für Makroberichte, Unterberichte, Subdatasets oder spezielle XPATH-Selektionen wichtig).
</blockquote>

==== Nutzung des Upload Servlets ====

Wenn Sie keinen Schreibzugriff auf den Ordner ''WEB-INF/reports'' haben, können Sie auch Templates über das [http://www.superx-projekt.de/doku/kern_modul/admin/f_Anpassungderwebxml.htm Upload Servlet ]direkt im Browser hochladen. Dazu müssen Sie in der web.xml die Dateiendungen .jrxml und (sofern benötigt) .jasper erlauben, siehe obiger Link.

Danach können Sie die Report Templates hochladen:

[[Datei:JasperReports-Handbuch_jr_upload1.png]]

Nach dem Upload können Sie das Template zunächst registrieren:

[[Datei:JasperReports-Handbuch_jr_upload2.png]]

und dann der jew. Maske zuordnen. Beachten Sie, dass der Pfadname relativ zum Ordner WEB-INF/reports angegeben wird, also in der Regel

../../default/custom

bzw. beim Mandantenbetrieb

../../Mandant-ID/custom


==== Probleme beim Deployment im Server ====

Es kann u.U. beim Deployment eines Berichts im Server das Problem auftreten, daß ein Bericht im lokalen iReport mit der XML-Datenquelle funktioniert, aber im Server für einzelne Merkmale kein Ergebnis geliefert wird. Dies hat folgende Ursache:


===== Feldnamen im Berichtsdesign weichen vom Datenbank-Feldnamen ab =====

Bei der lokalen Entwicklung in iReport werden die Berichte mit der Datenquelle XML erzeugt. In den Muster-JRXML-Dateien, die man über das Feld "Bericht erzeugen" generiert, sind die Felder über die folgende Notation deklariert:

<field name="Fakultät/Fachbereich (Schlüssel)" class="java.lang.String">

<fieldDescription><![CDATA[col[@id="4" and wert!=""]/wert]]></fieldDescription>

</field>

Dies bedeutet: Das Feld "Fakultät/Fachbereich (Schlüssel)" hat den Typ "String" und befindet sich im XML-Datenstrom in der vierten Spalte (col@id=4). Dabei befindet sich in Datenblattberichten im Spaltennamen immer ein "\n" vor der Zeichenkette "(Schlüssel)", um einen Zeilenumbruch im generischen Standardlayout zu erzeugen. Dieses "\n" wird dann für iReport und JasperReports automatisch durch ein Leerzeichen ersetzt.

Wenn die XML-Datenquelle nicht verändert wird, dann ist das Feld immer mit dem gleichen Inhalt gefüllt.

Wenn man den Bericht dann auf den Server kopiert und einbindet, ohne im Dateinamen "_xmlsource" zu verwenden, dann wird das Feld nicht über die Spaltennummer identifiziert, sondern über den Feldnamen, hier z.B. "Fakultät/Fachbereich (Schlüssel)". Das bedeutet, daß der Server genau diesen Feldnamen zurückliefern muss. Das kann u.U. abweichen:

* Der Server bzw. die zugrunde liegende Maske wurde verändert, so daß der Feldname geringfügig anders ist. Das sollte eigentlich nicht passieren, kann aber vorkommen.
* Beim Betrieb in HISinOne gibt es in allen Versionen bis 3.02 noch eine kleine Veränderung, wenn das Modul des zugrunde liegenden Datenblattberichts bzw. der Maske direkt per Tomcat-Start installiert wurde, und nicht in dem Edustore-Installation/Upgrade-Menü. Wenn die Module beim Tomcat Start in eine leere Datenbank installiert werden, dann werden Zeichenketten mit dem Feldinhalt "\n" verfremdet nach "n" (also der "\" wird entfernt). Das führt dann dazu, daß das Feld ohne den "\" in der jrxml-Datei deklariert wird, also z.B.

<field name="Fakultät/Fachbereichn(Schlüssel)" class="java.lang.String">

<fieldDescription><![CDATA[col[@id="4" and wert!=""]/wert]]></fieldDescription>

</field>

Wenn man danach dann einen Upgrade der jew. Komponente ausführt, dann wird die Spalte in der Maske umbenannt nach "Fakultät/Fachbereich'''\n'''(Schlüssel)" und der Feldname korrekt nach "Fakultät/Fachbereich''' '''(Schlüssel)" umgesetzt. Durch das "n" vor der Zeichenkette "(Schlüssel)" paßt der Feldname in der jrxml-Datei nicht mehr zum Ergebnis aus der Datenbank, und das Feld ist leer. So kann es passieren, daß ein Bericht in iReport funktioniert, im Server aber nicht. Im folgenden die Lösung.


===== Korrektur der Feldnamen im Berichtsdesign =====

Um sicherzustellen, dass der Feldname der jrxml-Datei mit der jeweils aktuell benutzten Datenbank-Version übereinstimmt, geht man wie folgt vor:

* Erzeugen Sie in Edustore eine HTML-Ausgabe der zugrunde liegenden Abfrage, bei Datenblatt-Berichten ist dies das "generische Standardlayout".
* Klicken Sie dann oben im Berichtskopf auf den Button "Bericht entwerfen" -> "leerer Bericht"
* Im Quellcode sehen Sie die Zeilen <field name="Berichtsname" class="java.lang.String"> ... Hier ist jedes einzelne Feld aus der Datenbank deklariert.
* Markieren Sie alle Zeilen bis zum letzten "<field...>"-Element, i.d.R. ist dies das Feld <field name="user"..., und kopieren Sie dies in die Zwischenablage
* Öffnen Sie die jrxml-Datei mit einem UTF-8-fähigen Editor, z.B. Jedit.
* Ersetzen Sie genau die "<field..."-Passage aus der Zwischenablage.
* Speichern Sie den Bericht, und testen Sie die Vorschau in JasperReports. Wahrscheinlich kommt eine Fehlermeldung "Field ... does not exist" o.ä., dann müssen Sie das Feld mit Suchen->Ersetzen umbenennen.
* Das machen Sie so lange, bis die Vorschau funktioniert. Danach können Sie die jrxml-Datei wieder auf den Server kopieren. Die Felddeklaration passt dann zum Server.


== Zuordnung von Default-Feldbelegungen zu Stylesheets ==

Es können für Stylesheets Default-Feldbelegungen für Stylesheets hinterlegt werden. Hintergrund dieser Funktion ist, dass bei speziellen Stylesheets standardmäßig beliebig viele Spalten vorbelegt werden können. In Datenblattberichten gibt es z.B. das Feld "Felder", in dem die auszugebenden Spalten angegeben werden. Aus Performancegründen sollten nur die Spalten ausgegeben werden, die auch benötigt werden. So kann dann z.B.für JasperReport Stylesheets hinterlegt werden können, welche Spalten auf jeden Fall benötigt werden. Der Anwender weiß nicht welche Spalten benötigt werden und würde im Normalfall alle Spalten ausgeben lassen um keine Fehlermeldung zu erhalten. Dadurch würde aber wiederum der Bericht unnötig lange dauern, da alle Spalten berechnet werden müssen, auch die, welche nicht benötigt werden.

Wenn Sie ein Stylesheet erstellt haben und dieses in SuperX eingebunden haben gehen Sie wie folgt vor:

Sie gehen in die Maske "Administration -> Tabelle suchen", geben dort bei Stichwort "stylesheet_field" ein und schicken die Maske ab.

[[Datei:JasperReports-Handbuch_stylesheet_field_maske.png]]

In der folgenden Ergebnistabelle klicken Sie bei "stylesheet_field_list" auf den "Bearbeiten" Button.

[[Datei:JasperReports-Handbuch_stylesheet_field_tabelle.png]]

In dem nun geöffneten Fenster sehen Sie alle Zuordnungen, welche bereits eingetragen sind. Hier wird aber lediglich das Stylesheet ausgegeben und nicht die Tabellen und Federzugehörigkeit. Dies hätte wegen der vielen Auswahlmöglichkeiten jeden Browser gekillt. Um Einzelheiten zu erfahren müssen Sie daher auf den Details-Button klicken. Auch wenn Sie eine neue Zuordnung erstellen möchten klicken Sie zunächst auf den Detail-Button eines beliebigen Stylesheets.

[[Datei:JasperReports-Handbuch_stylesheet_field_list.png]]

Jetzt können Sie die Zugehörigkeit des Stylesheets zu Tabelle und Feld ändern oder eine neue Zuordnung erstellen.

Achtung: Wenn ein Tabellenname ausgewählt und abgespeichert wurde, können nur Spalten dieser Tabelle ausgewählt werden. Wenn Sie die Tabelle ändern wollen, müssten Sie zunächst die Tabelle ändern, abspeichern und dieses Formular erneut aufrufen. Erst dann würden die Spalten der ausgewählten Tabelle in der Listbox Fieldname erscheinen.

[[Datei:JasperReports-Handbuch_stylesheet_field_edit.png]]

Um eine neue Verknüpfung zu erstellen klicken Sie zuerst auf den + Button oben rechts. Danach erscheint das gleiche Formular nur ohne ausgefüllte Felder. Hier können Sie das Stylesheet und den Tabellennamen auswählen und die dazu passende Spalte der Tabelle die Sie zuvor ausgewählt haben. Achten Sie darauf die Tabelle zu nehmen, welche im Datenblatt verwendet wird. Danach nur noch über das Diskettensymbol oben rechts abspeichern und eine Spalten-Stylesheet-Verknüpfung ist fertig. Diesen Schritt wiederholen Sie für jede Spalte, die Sie in dem JasperReport Bericht benötigen.

Ab Kernmodul 4.2 bzw. HISinOne 5.1 geht es noch komfortabler, Sie können hier auf einzelne Stylesheets filtern : Administration → Masken → Stylesheet suchen

Wählen Sie zunächst den Bericht aus, und klicken Sie dann rechts beim Bearbeiten-Button in der Spalte Felder-Vorbelegungen bearbeiten:

[[Datei:JasperReports-Handbuch_stylesheet_field.png]]

In dem Bearbeitungsformular können Sie Datensätze erzeuge, löschen etc.


== Kurzanleitung Direktaufruf von Jasper-Berichten von der Maske ==

Nach dem Abschicken der Maske kann man auch direkt auf den entsprechenden Jasper-Bericht umgeleitet werden. Es muss dazu in der Maske ein Feld geben mit dem Namen

tablestylesheet

und der relation

<<SQL>> select distinct filename,X.caption from sx_stylesheetsX, 
sx_mask_style S where X.tid=S.stylesheet_id and S.maskeninfo_id=23880

und zum Beispiel für Default der Maske 23880

<<SQL>> select distinct filename,X.caption from sx_stylesheets X,sx_mask_style S where X.tid=S.stylesheet_id and S.maskeninfo_id=23880 and S.ord=2

Für die Anzeige des Feldes tablestylesheet im Browser wird eine Berschriftung caption hinterlegt, damit auf der Maske "Bericht" erscheint. Im neuen Kern-Modul passiert dies automatisch.

Es ist möglich einen manuellen Eintrag in die Tabelle ''sx_captions'' einzufügen (siehe Maske Administration -> Maske -> Beschriftung suchen).

{| class="wikitable"
|-
!
!
!
!
!
|-
| tid
| table_name
| field_name
| locale
| contents_short
|-
| <<wird automat. vergeben>>
| felderinfo
| tablestylesheet
| de
| Bericht
|}

Außerdem muss man die Maske um ein Feld Ausgabeformat ergänzen, das die Art=1 hat und folgende relation:

select element_value,description from menu_element where element='Ausgabeformat' and nature::smallint<100 order by nature::smallint

Beispiel für Default Excel:

<<SQL>> select element_value,description from menu_element where element='Ausgabeformat' and description='Excel'

Achtung: Hier kommen erst Ergebnisse, wenn Sie das Kernmodul 4.1 / HISinOne 3.0 oder höher installieren.


== Spezielle Variablen ==

Im Berichtsdesign können neben den Feldern der Ergebnistabelle auch z.B. der Berichtsname, Erleuterung, user und standdatum benutzt werden. Zu finden sind diese im "Report Inspector" unter Fields. Um auch Hochschulspezifische Informationen wie Hochschulname oder Hochschul-Webadresse in einen Bericht importieren zu können wurden unter anderem die sx_captions Variablen "REPORT_HEADING_INSTITUTION" und "REPORT_HEADING_URL" integriert.

[[Datei:JasperReports-Handbuch_sx_captions_markiert.png]]

Diese können genau wie die anderen Fields in den Bericht per Drag&Drop gezogen werden.


== Makroberichte als Datenquelle für JasperReports ==

Sie können als Datenquelle für JR nicht nur einzelne Masken nehmen, sondern auch die Ausgabe von Makro-Masken. Dadurch können die verschiedenartigsten Informationen aus den normalen Masken für übergreifende Berichte genutzt werden.

Das folgende Beispiel zeigt, wie im KLR-Bericht "Berichtsblatt: Kennzahlen aus der Kostenrechnung" Teile verwendet werden, um einen eigenen JR zu erzeugen, der wiederum Elemente des Makroberichts als Unterbericht nutzt.

Zunächst rufen Sie den Makrobericht auf:

[[Datei:JasperReports-Handbuch_makro_html.png]]

Das Bild zeigt die ersten drei Elemente des Makros, sie werden mit einer Ordnungsnummer durchnummeriert.

Wir laden dazu die XML-Datenquelle herunter, die XML-Datenquelle binden wir wie [[#3.1.2.Datenquelle erzeugen|outline|gewohnt]] in JasperReports ein:

[[Datei:JasperReports-Handbuch_makro_datenquelle.png]]

Dann klicken wir im Browser über den Tabellen den Button rechts von "Bericht entwerfen" → Leerer Bericht. Die JRXML-Datei speichern wir wie [[#3.1.3.Template erzeugen|outline|gewohnt]].

Im Designer sehen wir nun bei den Feldern eine erweiterte Liste:

[[Datei:JasperReports-Handbuch_makro_jrxml.png]]

Wir sehen also, daß die Ergebnisspalten mit einem Präfix für die Tabellennummer versehen sind, z.B. "tab_0". Dadurch können wir die Tabellen und somit auch die jew. Spalten eindeutig identifizieren. Dies ist gleichzeitig der Hauptbericht. Das Detail-Band löschen wir (ist nicht nutzbar), stattdessen aktivieren wir ein Summary Band.

Dann erzeugen wir den [[#2.5.Unterberichte |outline|Unterbericht]] für Studierenden-VZÄ. Dazu speichern wir die obige jrxml-Datei z.B. mit dem Namen makro_beispiel_ub_stud.jrxml und entfernen das Titel-Band und Seitenfuß-Band. Dann fügen wir im Designer einen Parameter "ordnr" hinzu:

[[Datei:JasperReports-Handbuch_makro_ub_param.png]]

Der Unterbericht bekommt dann in der Report Query folgende Änderung:

[[Datei:JasperReports-Handbuch_makro_ub_report_query.png]]

Die Ordnungsnummer wird vom Hauptbericht übergeben und dient dazu, in der XML-Datenquelle auf die einzelne Tabelle zu filtern.

Zusätzlich geben wir noch einen weiteren Filter ein, damit die Summenzeilen aus der Originaltabelle nicht in die Kreuztabelle aufgenommen werden:

[[Datei:JasperReports-Handbuch_makro_ub_filter.png]]

Damit der Unterbericht auch "stand-alone" ausführbar ist, können Sie dem Parameter "ordnr" auch einen Standardwert zuweisen, hier z.B. "2":

[[Datei:JasperReports-Handbuch_makro_ub_ordnr_default.png]]

Nun können wir die [[#2.5.Unterberichte |outline|Kreuztabelle]] mit dem Assistenten erzeugen. Für unser Beispiel enthält die Kreuztabelle Studierenden-VZÄ nach Studiengang und Fachkennzeichen:

[[Datei:JasperReports-Handbuch_makro_ub_crosstab.png]]

Wir speichern den Unterbericht und binden ihn in den Hauptbericht im Summary Band ein. Dabei vergeben wir wie gewohnt die Parameter XML_LOCALE und XML_NUMBER_PATTERN. Außerdem erzeugen wir den Parameter "ordnr", und weisen diesem den Wert 2 zu, weil die Studierenden-Tabelle die Ordnungsnummer 2 hat (s.o.):

[[Datei:JasperReports-Handbuch_makro_hauptbericht_ub_params.png]]

Damit ist die Konfiguration beendet, der Bericht sieht so aus:

[[Datei:JasperReports-Handbuch_makro_hb_erg.png]]

Weitere Unterberichte lassen sich analog hinzufügen.

<blockquote>Hinweis zum Einbinden im Servlet: Unterberichte arbeiten nur mit der Datenquelle XML, daher müssen Sie die Datei des Hauptberichts mit dem Suffix "_xmlsource" versehen.
</blockquote>


== Kompatibilität von iReport mit JasperReports ==

Wenn Sie mit iReport Berichte erzeugen, sollte wie gesagt die iReport-Versionsnr. mit der JasperReports-Version übereinstimmen, die der jew. Server nutzt. In Edustore ist dies derzeit die Version 5.1.0. Wenn die Versionsnummern nicht übereinstimmen, dürfen Sie keinesfalls die *.jasper-Dateien von dem lokalen Arbeitsplatz zum Tomcat Server kopieren.

Darüber hinaus kann es auch weitere Abhängigkeiten geben, iReport bringt ein paar mehr Bibliotheken mit, als JasperReports. Wenn Sie dann eine jrxml-Datei auf den Server kopieren, könnte es eine Fehlermeldung geben in dem Stil

java.lang.NoSuchMethodError:...

Das Vorgehen ist hier wie folgt:

* Prüfen Sie zunächst, ob Sie die jeweilige Bibliothek wirklich brauchen.
* Wenn ja, dann ermitteln Sie aus dem Namen der fehlenden Klasse den Namen der *.jar-Datei. Meist reicht es, wenn Sie den Klassennamen in einer Suchmaschine eingeben, oder in einer speziellen Java-Suchmaschine wie http://www.jarfinder.com/
* Wenn Sie die jar-Datei identifiziert haben, können Sie diese von iReport-xxx/ireport/modules/ext/ in das webapps/superx/WEB-INF/lib Verzeichns kopieren.
* Danach müssen Sie Tomcat neu starten.

<blockquote>Achtung: gehen Sie beim Kopieren in den WEB-INF/lib Ordner möglichst '''sparsam''' um: manchmal gibt es zwischen einzelnen Bibliotheken unerwünschte und unvorhersehbare Querabhängigkeiten, z.B. nutzt eine iReport-Bibliothek xy.jar eine andere Bibliothek vz.jar, welche bereits im Tomcat Server vorhanden ist – aber mit einer anderen Versionsnummer. In diesem Falle kann es zu seltsamen Phänomenen kommen, die sehr schwer zu diagnostizieren sind, bis hin zu einer Instabilität des Servers. Man muss solche Kopiermaßnahmen auf jeden Fall gründlich testen! 
Unter uns: Wir nennen Probleme, die dadurch entstehen können, die "jar-Hölle"...
</blockquote>
Im folgenden sammeln wir ein paar Beispiele für gefahrlose Kopieraktionen.


==== iReport Grafiken in JasperReports ====

Bitte vermeiden Sie, iReport-spezifische "Themes" zu benutzen (z.B. "aegean"), denn dafür würden weitere Bibliotheken benötigt. Wenn Sie z.B. die folgende Fehlermeldung bekommen, wurde ein Theme benutzt:

[[Datei:JasperReports-Handbuch_grafik_theme_error.png]]

Dann sollten Sie die Einstellung für das Objekt (hier das Theme der Grafik) wieder auf default setzen.


==== Weitere Bibliotheken von iReport ====

Bei der Meldung

java.lang.NoSuchMethodError: org.objectweb.asm.ClassWriter

sollten Sie die Bibliotheken

iReport-xxx/ireport/modules/ext/asm.jar

und zur Sicherheit auch

asm-attrs.jar

in den WEB-INF/lib-Ordner kopieren.


= Troubleshooting =


== Report Problem: Class not set for bucket: <<Variable>> ==

Das Problem tritt in iReport 4.1.1 u.a. bei Kreuztabellen auf. Bei diesem Fehler fehlt in der jrxml-datei im Element <bucketExpression> Z.B.: class="java.lang.String". Diese einfach im Editor ergänzen und es funktioniert. Beispiel:

Aus :

<bucketExpression>

wird:

<bucketExpression class="java.lang.String">


== Die jasper Datei ==

Die jasper Datei ist die kompilierte jrxml. Wenn ein Bericht übertragen werden soll, z.B. von dem Entwickler auf den Server oder von dem Development System auch das Produktivsystem immer nur die jrxml Datei übertragen, da es bei Versionsunterschieden in JasperReport zu Fehlern kommt, wenn die Kompilierte Version zur Verfügung steht. Sobald der Bericht ausgeführt wird, erstellt (kompilliert) JasperReports automatisch die jasper Datei.

Wenn die jasper Datei zur verfügung steht, wird auch nur noch diese von JasperReports verwendet und nicht mehr neu kompiliert. Falls Sie also einen Bericht weiter entwickelt haben oder eine neue Version einspielen, löschen Sie direkt die jasper Datei. Ansonsten werden die Änderungen nicht wirksam.


== Im Excel Export fehlen Felder ==

In Excel werden überlappende Elemente nicht angezeigt. Wenn also 2 Elemente übereinander liegen wird in Excel nur das oberste (welches im Vordergrund liegt) angezeigt. Hier ist besonders drauf zu achten, dass visuell 1px Abstand zwischen den Elementen Platz ist. Wenn von beiden Elementen jeweils eine Linie zu sehen ist, ist es korrekt. Wenn nicht, zählt das schon als Überlappung. Dafür im iReport Designer am besten ganz nah heran zoomen um diesen Abstand zu prüfen.

Hier ein Beispiel. Die beiden oberen Elemente überlappen, die unteren nicht:

[[Datei:JasperReports-Handbuch_ireport_excel.png]]


== Hinweis für HisInOne 7.0 Kompatibilität ==

Jrxml-Dateien, die unter iReport 4.1.3 entwickelt wurden und in HisInOne 7.1 funktionieren, können in 7.0. zur Fehlermeldung führen:

java.lang.NoClassDefFoundError: net/sf/jasperreports/compilers/GroovyEvaluator

In der jasperreports5.1.0 (hisinone 7.0) ist die Klasse GroovyEvaluator nicht enthalten, für 7.1 ist die jasperreports-6.1.0.jar enthalten, die enthält den GroovyEvaluator.

Workaround:

language="groovy"

ändern in

language="java"


== HTML Export keinen whitespace ==

Normal macht JR bei HTML-Exporten für den „Seitenumbruch“ eine Reihe von Leerzeilen. Um dies zu vermeiden, setzen Sie die Property IgnorePagination=true:

<jasperReport xmlns="http://jasperreports.sourceforge.net/jasperreports" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://jasperreports.sourceforge.net/jasperreports http://jasperreports.sourceforge.net/xsd/jasperreport.xsd" name="Kaufm. Quartalsbericht" language="groovy" pageWidth="2925" pageHeight="565" orientation="Landscape" columnWidth="2925" leftMargin="0" rightMargin="0" topMargin="0" bottomMargin="0"

isIgnorePagination="true">


== UUID's ==

In Jaspersoft Studio wird an jedes Element eine lange UUID angehängt, in aktuellen Versionen von SuperX/ Edustore macht das keine Probleme. In älteren Versionen bzw. in iReport 4.* schon. Damit der JasperReport abwärtskompatibel ist, muss diese gelöscht werden. Bei großen Berichten taucht diese aber unter Umständen mehrere hundert Mal auf. Hier kann in JasperSoft Studio in dem "Source"-Reiter des Berichtsdesigners nach folgender Regular Expression gesucht werden und diese mit einem Leerzeichen ersetzt werden:

uuid="[0-9a-z-]{36}"


= Weitere Dokus =

<blockquote>Ahammad, S. (2010). iReport 3.7.Learn how to use iReport to create, format, and export reports. Birmingham: Packt
</blockquote>
<blockquote>Haneke, U. et al. (2010). Open Source Business Intelligence. Möglichkeiten, Chancen und Risiken quelloffener BI-Lösungen. Wien: Hanser
</blockquote>
<blockquote>Toffoli, G. (2007). The definitive guide to iReport. Berkeley, CA: Apress
</blockquote>
<blockquote>Noch mehr Infos (nur Englisch) erhält man unter: 
http://jasperforge.org/plugins/project/project_home.php?projectname=ireport
</blockquote>
<blockquote>und natürlich unsere Website:
</blockquote>
<blockquote>http://www.superx-projekt.de/doku/entwicklung/iReport-Handbuch/main.htm
</blockquote>
<blockquote>
</blockquote>

Berichtsdesign mit JasperReports

2026-07-06T07:51:38Z

Andrek: /* Unterschiede iReport und JasperSoft Studio */

Berichtsdesign mit JasperReports

von Daniel Quathamer & Andre Knieschewski


= JasperReports installieren und konfigurieren =


== Voraussetzungen ==

* Jasperreports ist eine Laufzeitumgebung fürs Reporting, die in java-basierte Reporting Software integriert werden kann. Der Download ist hier: https://sourceforge.net/projects/jasperreports/. Dieses Paket enthält kommandozeilenbasierte Demos und die benötigten Libraries. Die Demos sind sehr nützlich und als Referenz gut nutzbar.
* Die Entwicklungsumgebung für JasperReports heißt "Jaspersoft Studio" und kann bezogen werden von https://community.jaspersoft.com/project/jaspersoft-studio. Es enthält auch obige Laufzeitumgebung. 
Da es ein Eclipse Plugin ist, können Sie es auch direkt in Ihrem Eclipse installieren (Menü Help → Eclipse Marketplace → Suchwort "Jaspersoft". Dort können Sie aber nur die jeweils aktuelle Version installieren.

Da der Download bei Jaspersoft nun nur für registrierte Nutzer zur Verfügung steht, hier noch ein Link für den Download: https://sourceforge.net/projects/jasperstudio/files/

* Für altere Projekte wurde auch iReport verwendet. Da es ein paar Bugs in den verschiedenen Versionen gibt, empfehlen wir zu der Erstellung von JasperReport Berichten die iReport Version 4.1.3, auch wenn in Edustore die Version 5.1.0 verwendet wird. Download der passenden Version von iReport von http://sourceforge.net/projects/ireport (dort auf "files"->"iReport" klicken, dann erhalten Sie Links auf die jeweilige Version.
* Für Demos & Deployment auch Apache ANT http://ant.apache.org/
* Java 1.8 JRE oder höher


== JasperReports und Jaspersoft Studio ==

JasperReports ist das Programm, das fertige Berichte erzeugen kann. Es besitzt (außer einer Vorschauansicht der Berichte) keine graphische Oberfläche. Für das Entwerfen von Berichten ist ''''''Jaspersoft Studio'''''' geeignet. Um es noch ein wenig zu veranschaulichen könnte man sagen, dass wenn ein JasperReport das Worddokument wäre, dann wäre Jaspersoft Studio z.B. Microsoft Word.


=== Jaspersoft Studio ===

Nach dem Download benötigen Sie Java 1.8 oder höher zum Ausführen. Nach dem Entpacken können Sie die Anwendung direkt starten.

Bei JasperSoft Studio wird als Grundlage Eclipse verwendet. Wenn man JasperSoft Studio herunter lädt, erhält man automatisch Eclipse mit dabei. JasperSoft Studio kann [http://community.jaspersoft.com/project/jaspersoft-studio hier] heruntergeladen werden.

Wenn lieber ein bereits vorhandenes Eclipse verwendet werden soll und Jaspersoft Studio dort als Plugin installiert werden soll, gibt es 2 Wege:

<ol style="list-style-type: decimal;">
<li>Unter Help → Eclipse Marketplace kann nach „Jaspersoft“ gesucht werden und das Plugin installiert werden
[[Datei:JasperReports-Handbuch_jaspersoftstudio_plugin_install1.png]]</li>
<li>Man kann auch über die Marketplace Webseite von Eclipse das Plugin Jaspersoft Studio suchen und das Icon per Drag&Drop nach Eclipse ziehen. Dann wird das Plugin automatisch installiert. [https://marketplace.eclipse.org/content/jaspersoft-studio Hier] die Webseite. (Bei mir hat das Drag&Drop leider nicht funktioniert. Das kann an Linux liegen. Unter Windows wird es sicherlich funktionieren.)</li></ol>


==== Jaspersoft Studio Einstellungen ====

Unter Windows - > Preferences → Jaspersoft Studio können Sie verschiedene Einstellungen vornehmen. Wichtig in der Menüpunkt "Compatibility": wählen Sie dort die JR-Version, die auch Ihre Ziel-Platform enthält.

Im Dateimanager von JasperSoft Studio gibt es Eclipse-typisch ein "virtuelles" Dateisystem mit dem Standardnamen "MyReports", zumindest beim Speichern von Dateien. Dieses Dateisystem liegt physisch im Ordner <<Home-Verzeichnis>>/JaspersoftWorkspace/MyReports.

Beim Öffnen von Dateien können Sie direkt mit "Open File" aufs normale Dateisystem zugreifen.


==== Jaspersoft Studio Entwurfsbereich ====

Hier eine Übersicht des Entwurfsbereichs, in rot finden Sie Erläuterungen:

[[Datei:JasperReports-Handbuch_jaspersoft_designer.png]]

Die Unterfenster können Sie Eclipse-typisch beliebig anordnen. Oben ein Beispiel.


===== Jaspersoft Studio Sortierung und Filterung der Datenquelle =====

Wenn die Datenquelle definiert ist, kann /sollte der Bericht die Sortierung und Filterung der Daten festlegen. Dies ist etwas versteckt im Designer mittig oberhalb des Entwurfsbereichs:

[[Datei:JasperReports-Handbuch_jaspersoft_design_query.png]]

Im "Dataset and Query Dialog" sind die Felder der Datenquelle aufgeführt. Unten finden Sie die Reiter "Sorting" und "Filter Expression". Dort pflegen Sie beides.


===== Jaspersoft Studio Berichtsdesign und Vorschau =====

Im Designmodus können Sie den Bericht entwerfen, oder den XML-Quellcode. Beim Klick auf den Reiter "Preview" bekommen Sie eine Vorschau des Berichts:

[[Datei:JasperReports-Handbuch_jaspersoft_design_preview.png]]

Oberhalb der Vorschau können Sie die Datenquelle (d.h. den "Data Adapter" angeben, und rechts daneben die Anwendung, die den Bericht zur Anzeige bringt ("Viewer"). Voreingestellt ist hier der Java-interne Viewer von JasperReports, Sie können den aber umstellen z.B: auf PDF oder Excel.

Mit Klick auf das grüne Dreieck führen Sie den Bericht aus und erhalten die Vorschau.

<blockquote>Achtung: Es ist aufgefallen, dass beispielsweise Fettdruck in der PDF-Vorschau nicht angezeigt wird. Im Java-Preview und aus der Weboberfläche geladen, ist der Fettdruck ersichtlich.
</blockquote>

===== Jaspersoft Studio Berichtsstruktur =====

Im "Outline View" sehen Sie die Struktur des Berichts, d.h. aktive "Bänder" und Metadaten:

[[Datei:JasperReports-Handbuch_jaspersoft_design_outline.png]]

Die Elemente unter "Fields" werden bei Nutzung in [[#3.1.3.Template erzeugen|outline|Edustore]] automatisch gefüllt. Alles weitere definieren Sie.


===== Jaspersoft Studio Elemente bearbeiten =====

Wenn Sie im Design Modus ein Element markieren, wird es automatisch im Outline und in dem Reiter "Properties" selektiert:

[[Datei:JasperReports-Handbuch_jaspersoft_design_properties.png]]

Im Outline zeigt es lediglich, wo es sich befindet, und im Reiter "Properties" können Sie Formatierung, Anzeige etc. bearbeiten.


=== iReport ===

[[Datei:JasperReports-Handbuch_welcome.png]] Das Paket enthält bereits die Laufzeitumgebung JasperReports, diese muss also nicht separat installiert werden. Nichtsdestotrotz empfiehlt sich der Download, denn in dem JasperReports-Paket befinden sich viele lehrreiche Demo-Berichte.

Die Windows-Version beinhaltet auch einen Installer. Um diesen zu nutzen sind Admin-Rechte erforderlich.

Alternativ bzw. unter Linux ist iReport ohne Installation direkt nach dem Entpacken lauffähig. Wenn Sie auch Scriptlets erstellen wollen, müssen Sie nicht nur eine Java-Laufzeitumgebung (JRE) installieren, sondern ein JDK, und die Datei $JAVA_HOME/lib/tools.jar nach iReport-<<Versionsnr.>>/ireport/libs kopieren. Danach müssen Sie iReport neu starten.

Start unter Windows: iReport-<<Versionsnr.>>/bin/ireport.exe

Start unter Linux: iReport-<<Versionsnr.>>/bin/ireport


==== iReport Einstellungen ====

Als erstes sollten Sie die Anwendungen einstellen, mit denen iReport generierte Berichte anzeigen soll:

Im Menü Extras-> Optionen wählen Sie im Reiter "iReport"-"Viewers" die entsprechenden Anwendungen:

[[Datei:JasperReports-Handbuch_ireport_viewers.png]]


==== iReport Entwurfsbereich ====

Der Entwurfsbereich bzw. "Designer" hat einen recht komplexen Aufbau. Sie können die Fenster und Seitenbereiche zwar recht flexibel anpassen, aber hier ist die Auslieferung:

[[Datei:JasperReports-Handbuch_designer_ueberblick.png]]

Die wichtigen Bereiche sind hervorgehoben:

* Berichtsstruktur: Welche Seitenbereiche gibt es?
* Datenquelle: Welche Datenbank wird genutzt?
* Abfrage: Was ist die konkrete Abfrage für den Bericht?
* Elemente: Welche Elemente kann ich einfügen, und welche Eigenschaften haben sie?
* Vorschau: wie sieht der Bericht "gedruckt" aus?
* Fehlerausgabe: Jeder Bericht wird "kompiliert", dazu gibt es eine Fehlerausgabe

Im Reiter "Preview" kann man sich eine Vorschau des Ausdrucks anzeigen lassen.


=== Unterschiede iReport und JasperSoft Studio ===

Mit der Version 5.5 wurde die Entwicklung von iReport eingestellt, die Firma JasperSoft empfiehlt seit dem die Benutzung von JasperSoft Studio. Nach unseren Erfahrungen ist die Arbeit mit iReport 4.1.3 (die letzte stabile Version) hier und da "leichtgewichtiger" und einfacher, ganz zu schweigen vom Overhead, den JasperSoft Studio mit Eclipse einbringt. Besonders nervig empfanden wir es, dass JasperSoft Studio anders als iReport verschiedene Objekteigenschaften in Reitern organisiert, und bei jedem Wechsel der Markierung eines Berichtselements muss man in JasperSoft Studio wieder zum richtigen Reiter wechseln.

Andererseits ist JasperSoft Studio kompatibel mit neueren JR-Möglichkeiten. Insbesondere bei dem Umgang mit Diagrammen gibt es in JasperSoft Studio erheblich mehr Möglichkeiten, z.B. Chart Customization. Außerdem ist es vorteilhaft, wenn Sie ohnehin Eclipse nutzen. Sie sollten für Ihre Arbeit also abwägen ob Sie die neueren Möglichkeiten im jeweiligen Bericht überhaupt brauchen, ggf. sind Sie mit iReport besser bedient. Aber das ist Geschmackssache.

<blockquote>Beachten Sie aber bitte: sobald Sie einen Bericht mit JasperSoft bearbeitet und gespeichert haben, ist er mit iReport 4.1.3 nicht mehr bearbeitbar, bzw. nur wenn Sie die [[Berichtsdesign_mit_JasperReports#UUID's|UUIDs]] entfernt haben.
</blockquote>
Beide Produkte befinden sich noch im Einsatz, daher hier nur ein paar Kapitel zur Handhabung der jew. Software.


==== Handhabung ====


===== Preview =====

Bei iReport waren die Buttons für Designer und Preview immer oben.

[[Datei:JasperReports-Handbuch_jss-ir_preview1.png]]

Bei Jaspersoft Studio liegen die Buttons unten:

[[Datei:JasperReports-Handbuch_jss-ir_preview2.png]]


===== Palette =====

Die Palette ist bei iReport und Jaspersoft Studio an gleicher Position zu finden.

Ireport:

[[Datei:JasperReports-Handbuch_jss-ir_palette1.png]]

Jaspersoft Studio:

[[Datei:JasperReports-Handbuch_jss-ir_palette2.png]]


===== Objekt-Eigenschaften =====

Die Objekt-Eigenschaften liegen auch an der gleichen Stelle, jedoch sind bei Jaspersoft Studio die Gruppierungen der Eigenschaften in Karteireiter unterteilt. Bei iReport ist es einfach eine lange Liste mit Unterteilungen.

iReport:

[[Datei:JasperReports-Handbuch_jss-ir_properties2.png]]

Jaspersoft Studio:

[[Datei:JasperReports-Handbuch_jss-ir_properties1.png]]



== JasperReports als Kommandozeilen-Tool ==

In der JasperReports-Distribution befindet sich ein ANT-Script, das mehrere Berichte erzeugen kann.

cd demo/samples

Beispiel xmldatasource:

cd xmldatasource

ant -p

Die Ausgabe ist:

[[Datei:JasperReports-Handbuch_ant_xmldatasource.png]]

Es werden, je nach Auswahl pdf-, Excel- oder andere Berichte erzeugt. Mit dem Target "test" werden alle Targets durchlaufen.

ant test

Achtung: manche Demos brauchen eine laufende HSQLDB (siehe demo/hsqldb).


= Datenquellen =

Allgemein unterstützt JasperReports verschiedene Datenquellen, z.B. relationale Datenbanken, Excel, CSV oder XML. Auch Webservices sind möglich. Speziell für SuperX/ HISinOne-BI gibt es spezielle Datenquellen-Vorgaben, damit Sie die Daten auch im Server-Betrieb nutzen können. Hier also nur die allgemeinen, also SupeRX/BI-unabhängigen Quellen, wenn Sie JasperReports am lokalen Arbeitsplatz nutzen.


== Datenquelle Datenbank ==

Eine relationale Datenbank ist in JasperSoft Studio als "Data Adapter" einzurichten. Oben links befindet sich der Dialog zum Erzeugen (1) des Data Adapter, und dann darunter die Zeile "Database Jdbc Connection" (2):

[[Datei:JasperReports-Handbuch_data_adapter1.png]]

Dort geben Sie dann die jdbc-spezifischen Daten an (Datenbanktyp, Name etc.).

<blockquote>Achtung: die Nutzung setzt eine direkte Datenbankverbindung zum DB-Server voraus, an vielen Unternehmenanwendungen wird dies nicht mehr erlaubt. Ggf. fragen Sie bei Ihren Systemadministrator/innen nach.
</blockquote>


== Datenquelle Excel-Datei ==

Eine Excel Datei ist in JasperSoft Studio als "Data Adapter" einzurichten. Hier ein Beispiel:

[[Datei:JasperReports-Handbuch_datenquelle_excel_1.png]]

Die Excel Datei hat vier Spalten und eine führende Zeile mit den Spaltenüberschriften. Achten Sie darauf, dass die Datentypen der Spalten in Excel dem Inhalt entsprechen. Hier die Spalten:

* Frage Nr.
* Text
* Mit_ohne_schule
* Summe

Aus der Excel-Datei erzeugen Sie einen "Data Adapter". Der Data Adapter vom Typ "Excel File" hat ein paar Eigenschaften:

[[Datei:JasperReports-Handbuch_datenquelle_excel_2.png]]

Danach können Sie in einem Berichtsdesign die Datenquelle definieren:

[[Datei:JasperReports-Handbuch_datenquelle_excel_5.png]]

Sie wählen dort oben links zunächst den "Data Adapter" aus (1), und klicken dann rechts auf "Read Fields" (2):

[[Datei:JasperReports-Handbuch_datenquelle_excel_3.png]]

Aus der Datenquelle werden dann die Datenfelder (3) und Inhalte (Reiter "Data preview") automatisch übernommen.


= Berichtsdesign =

Das Erstellen eines Berichtes erleichtert JasperReports wesentlich. Dennoch wird man sich damit etwas beschäftigen müssen, um ein vernünftiges Ergebnis zu erhalten.

Zuerst muss man den Bericht öffnen. Das geschieht über „Datei“ → „Open“ → Bericht auswählen → auf „Öffnen“ klicken. Nun noch oben links die für diesen Bericht erstellte Datenquelle auswählen und man kann loslegen.

JasperReports bezeichnet die Ausgabebereiche als Bänder. Ein Band ähnelt einer Zeile. Es reicht über die komplette Seitenbreite. Die Höhe kann dabei selbst bestimmt werden und wird dem Informationsgehalt angepasst. Das Band „Detail 1“ ist so etwas wie das Hauptband, in dem dann die Informationen zeilenweise ausgegeben werden. Es wird also eine Schleife über die Daten (Tabelle) ausgeführt und für jeden Datensatz ein mal das Detail Band ausgegeben. Die linke Spalte könnte z.B so aussehen:

[[Datei:JasperReports-Handbuch_iReport-iReport_Leiste_Neu.jpg]]

Hier sieht man, das das Band „Detail 1“ aktiv ist und die anderen wie „Title“ noch nicht. In den Gruppen „Fields“ und „Variablen“ befinden sich die Felder (Spalten) aus der Ergebnistabelle und interessante Variablen wie Seitenzahl, die man nun einfach in das bestehende Band „Detail 1“ per „Drag and Drop“ ziehen kann.

[[Datei:JasperReports-Handbuch_iReport-Feld_Name.jpg]]

Wenn man z.B. in der Gruppe Fields das Feld „Name“ hat und dies in das Band „Detail 1“ zieht,befindet sich ein Platzhalter im Entwurfsbereich:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_1_Namen.jpg]]

Wenn Sie dann auf „Preview“ klicken, wird eine Vorschau des Berichts angezeigt.

[[Datei:JasperReports-Handbuch_iReport-Designer_Preview.jpg]]

Es werden alle Namen aufgelistet, die in der Datenquelle vorhanden sind:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_1_Namen_Ergebnis.jpg]]

Sie können das Layout der Ausgabe (Schriftart, Größe) über die Eigenschaften des Feldes variieren.

Um wieder zurück in den Entwicklermodus zu kommen klickt man einfach wieder auf den Reiter "Designer".

Die Bänder „Title“, „Page“ usw. kann man mit einem Rechtsklick und dann „Add Band“ hinzufügen und auch wieder mit einem rechtsklick und dann „Delete Band“ wieder entfernen. Diese Bänder haben bestimmte Eigenschaften. Z.B. Band „Titel“ wird nur einmal auf der ersten Seite abgebildet, Band „Page Header/Footer“ auf jeder Seite am Anfang/Ende.


== Sortierung und Filtern ==

Normalerweise verarbeitet JasperReports die Datensätze zeilenweise in der Reihenfolge, in der sie bereitgestellt werden. Sie können im Entwurfsmodus die Sortierung bzw. Filterung der Datensätze anpassen:

[[Datei:JasperReports-Handbuch_ireport_sort1.png]]

Klicken Sie auf das Icon mit der Tonne und Sie gelangen in die Einstellungen für die Datenquelle.

[[Datei:JasperReports-Handbuch_ireport_sort2.png]]

Im Button Sortieren können Sie nach allen Feldern des Berichts aufsteigend bzw. absteigend sortieren.

[[Datei:JasperReports-Handbuch_ireport_sort3.png]]

Im Button "Filter expression" können Sie eine Formel definieren, um die Gültigkeit von Datensätzen zu definieren:

[[Datei:JasperReports-Handbuch_ireport_filter1.png]]

Z.B. die Expression ".contains("12") würde auf alle Datensätze filtern, die im Feld die Zeichenkette "12" enthalten. Weitere Infos im Kapitel zum [[#2.9.Expression Editor|outline|Expression Editor]].


== Listen ==

Listen lassen sich einfach erstellen, indem man die jeweiligen Felder ins Detail-Band zieht. Manchmal kann es vorkommen, dass Textfelder "überlaufen", d.h. die rechteckige Box, die das Feld markiert, ist zu klein für den Feldinhalt. Beispiel:

[[Datei:JasperReports-Handbuch_listen_stretch.png]]

In diesem Falle muss man das Attribut des jew. Felder (hier "Fächergruppe") "Text Field properties > Stretch with overflow" ankreuzen.

Achtung: wenn das Feld Teil einer tabellarischen Auflistung ist, muss man die anderen Element mit der Eigenschaft "Stretch type → Relative to tallest object" versehen, hier z.B. die Felder "Studienfeld" und "Studienbereich".

Bei vielen Zeilen ist es übersichtlicher, jede zweite Zeile farbig zu hinterlegen. Dieser Trick ist im Abschnitt Tabellengestaltung [[#2.4.3.Zeilen alternierend einfärben|outline|erläutert]].


== Gruppierung ==

Wichtige Vorbemerkung zum Gruppieren: JasperReports setzt bei der Gruppierung voraus, dass die Datensätze der Datenquelle nach den Gruppierungsmerkmalen sortiert sind. Alle Merkmale, nach denen Sie gruppieren, sollten also entweder direkt in der Datenquelle sortiert sein, oder in JasperReports im [[#2.1.Sortierung und Filtern|outline|Berichtsentwurf]].


=== Gruppen definieren ===

Zu den Standardbändern kann man nun auch noch selbst definierte Gruppen hinzufügen. Mit einem Rechtsklick auf den obersten Knoten → „Add Report Group“ öffnet sich ein Fenster in dem man der Gruppe einen Namen geben kann und das Objekt wählt für das die Gruppe erstellt wird.

[[Datei:JasperReports-Handbuch_designer_add_group.png]]

<blockquote>Achtung: wenn Sie mehrere Gruppierungsebenen benötigen, dann sollte die Reihenfolge des Hinzufügens der Gruppen "top-down" verlaufen, d.h. zuerst die oberste Gruppierung hinzufügen, dann die Gruppe darunter usw.
</blockquote>
In dem folgenden Beispiel wird die Gruppe „Monat“ gewählt und in dem nächsten Schritt mit Header und Footer hinzugefügt:

Man zieht das Feld „Namen“ in das Band „Detail“ und „Monat“ in das erstellte Band „Monat Group Header 1“. Aus der Palette rechts oben (wenn nicht vorhanden bekommt man es über „Fenster“ → „Palette“) zieht man einen „Static Text“ in das Band „Monat Group Header 1“ vor der Ausgabe des Monats, benennt das Feld „Monat:“ und noch eine Linie darunter. Zusammen sollte es so aussehen:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_Monat_Namen.jpg]]

Wenn man nun auf „Preview“ klickt erhält man als Ergebnis:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_Monat_Namen_Ergebnis.jpg]]


=== Seitenumbrüche ===

Damit eine Gruppe nicht durch einen Seitenumbruch auseinandergerissen wird, gibt es einige Einstellungen in dem Band der Gruppe. Dazu einfach auf das jeweilige Band klicken, für welches die Einstellungen vorgenommen werden sollen und dann in „Eigenschaften“ → „Group properties“ → „Keep Together“ anklicken oder wenn man möchte „Reprint header“ um den "Header" der Gruppe am Seitenkopf zu wiederholen.

Sie können auch angeben daß vor jedem Gruppierungswechsel ein Seitenumbruch ausgeführt wird:

[[Datei:JasperReports-Handbuch_designer_add_group_new_page.png]]

Mit "Start on a new page" wird eine neue Seite bei jedem Gruppenwechsel begonnen. Speziell beim Export nach Excel kann dies in Tandem mit Arbeitsblättern nutzen, siehe [[#2.19.2.Excel-Export in einzelne Tabellenblätter|outline|unten]].


=== Gruppensummen ===

Gruppensummen kann man im Kopf oder Fuß einer Gruppe anlegen. Sie aktivieren z.B. den Gruppenfuß im Report Inspector, und ziehen dann das Feld Summe in den Entwurfsbereich. Beim "Fallenlassen" werden Sie gefragt, ob Sie den jew. Wert oder eine Aggregatfunktion nutzen wollen. Für Zwischensummen wählen Sie "Sum":

[[Datei:JasperReports-Handbuch_designer_add_group_foot1.png]]

Im Entwurfsbereich setzen Sie noch ein Label bzw. "Static Text"-Element rechtsbündig davor, und setzen beide Elemente fett:

[[Datei:JasperReports-Handbuch_designer_add_group_foot2.png]]


=== Gruppierung ohne eigenes Band ===

Bei der Gruppierung in JasperReports wird in der Regel ein horizontales Band für die Gruppierungsebene angelegt. Das führt dazu, daß man zeilenorientiert gruppiert. In manchen Fällen kann es gewünscht sein, in den Spalten einer Tabelle zu gruppieren. Hier ein Beispiel für das Ziel:

[[Datei:JasperReports-Handbuch_gruppierung_spalten1_vorlage.png]]

In dem Beispiel wird in den Zeilen nach dem Merkmal '''Fach''' gruppiert. Zusätzlich wird noch in den Spalten nach Fachsemestern gruppiert. Um dieses Layout zu realisieren, muss man wie folgt vorgehen:

Erzeugen Sie ein Column Header Band, und ein Group Footer-Band für die Gruppierungsebene Fach. Warum Group Footer? Weil innerhalb des Fachs nochmal gruppiert werden soll, und daher erst nach dem Gruppieren nach Fach nach Fachsemestern gruppiert wird. Ein Detail-Band gibt es hier nicht.

[[Datei:JasperReports-Handbuch_gruppierung_spalten3_band.png]]

Erzeugen Sie eine neue Variable z.B. mit dem Namen "fs1" für erstes Fachsemester, und geben Sie der Variable folgende Eigenschaften:

[[Datei:JasperReports-Handbuch_gruppierung_spalten2_variable_1fs.png]]

Zur Erläuterung: Die Variable filtert die Datensätze gemäß dem Ausdruck in Variable Expression, und tut dies auf der Gruppierungsebene "fach". Die Variable Expression ist eine für unsere Zwecke sehr nützliche Java-Kurzfassung einer IF-THEN-Bedingung, und meint:

<blockquote>Wenn der Inhalt des Feldes "Anzahl Fachsemester" gleich 1 ist, dann gib die Summe der jew. Studierenden aus, wenn nicht, dann gib 0 aus.
</blockquote>
Analog kann man noch die Variable "fsgr13" für "Fachsemester > 13" anlegen.

Danach kann man die Variablen "fs1" und "fsgr13" in das Band "Fach Group Footer 1" ziehen, und noch das Feld "Summe" für die Gesamtsumme. Dann tragen wir im Column Header Band noch die Spaltenüberschriften ein. Insgesamt sieht Berichtsentwurf dann so aus:

[[Datei:JasperReports-Handbuch_gruppierung_spalten4_band.png]]

Und das Ergebnis sieht so aus:

[[Datei:JasperReports-Handbuch_gruppierung_spalten5_band.png]]

Fertig. Man könnte nun noch weitere Fachsemester-Intervalle einfügen, oder z.B. eine Summe der Studierenden in der Regelstudienzeit.


=== Gruppierung mit virtuellen Dimensionen ===

Wenn Sie nach Feldern gruppieren wollen, die es in Ihrer Datenquelle gar nicht gibt (z.B. nach Aggregationen von Mekrmalskombinationen), dann können Sie auch Variablen mit speziellen Formeln anlegen, und diese dann in die Gruppierung aufnehmen.

<blockquote>Wichtig: Wenn die Gruppierungsvariable nicht im Summary Band genutzt wird, muss der resettype der Variable auf „None“ gesetzt werden.
</blockquote>
Im Abschnitt zu [[#2.5.4.Kreuztabellen mit virtuellen Dimensionen|outline|Kreuztabellen]] wird z.B. gezeigt, wie die Fächer Mathe, Physik und Biologie in einen neuen Wert "Naturwissenschaften" transformiert werden.


=== Variablen und Gruppierung ===

Beim Anlegen von Gruppen-Bändern und beim Ziehen von Feldern in das jew. Gruppenband legt JR automatisch eine Variable an, mit der jew. Aggregationsfunktion. Diese Variable hat folgende Eigenschaften:

Expression: das Feld, aus dem die Variable gespeist wird

Calculation: Die Aggregatfunktion, z.B. "sum"

Reset Type: Die Gruppierungsebene

Wenn Sie die Variable in Textfeldern des Gruppenbandes nutzen, gibt sie jeweils den richtigen Wert an, egal ob Gruppenkopf oder Fuß.

Wenn Sie aber mit "Print-when-Expressions" im Gruppenband arbeiten und auf die Variablen zugreifen, funktionieren diese standardmäßig nur im Gruppenfuß, weil erst am Ende der Gruppe der Wert bekannt ist. In diesem Fall müssen Sie der Variable auch eine "Initial Value Expression" mit dem jew. Feld geben.


=== Berechnungen auf Gruppenebene ===

Wenn Sie auf der Gruppenebene Berechnungen, z.B. Mittelwerte, durchführen wollen, gibt es einige Fallstricke:

* Die in JR eingebauten Funktionen wie "avg" arbeiten auf Gruppenebene nicht immer exakt.
* Komplexere Formeln auf Gruppenebene in Variablen abzubilden und diese dann das Quelle für Textfelder zu nehmen hat bei uns nicht geklappt.

Hier unser Vorgehen:

* Definieren Sie auf der Ebene der jew. Gruppe eine Variable mit der Gesamtsumme, und eine mit der Summe der zu mittelnden Werte. Diese Variablen haben als "reset Type" die jew. Gruppierungsebene.
* Im Textfeld, das Sie ausgeben, verwenden Sie dann die Berechnungsformel, z.B. einen Quotienten. Verwenden Sie für die Berechnung nicht eine neue Variable, sondern fügen Sie die Formel direkt in das Textfeld ein.

Im folgenden ein Beispiel: Wir haben eine Absolventenliste pro Studiengang und Semester, darin werden dann Mittelwerte von Abschlussnoten gebildet. Die Datenquelle hat summierte Zeilen pro Note:

[[Datei:JasperReports-Handbuch_notenschnitt_daten.png]]

Im obigen Beispiel haben wir in der Zeile 5 eine Absolventin mit der Note 1,1. In der letzten Zeile haben wir zwei Absolventinnen mit der Note 1,2.

Würden wir den Notenschnitt manuell berechnen, müßten wir die Notensumme (Spalte H*K) ermitteln, hier wäre der Wert 32,3. Die Summe der Absolventen in Spalte K wäre 16, d.h. der Notenschnitt wäre 32,3/16 = 2,02.

In JasperReports wäre der Entwurf wie folgt:

[[Datei:JasperReports-Handbuch_notenschnitt_design1.png]]

Wir haben eine Variable "Summe_1" auf der Ebene des Semester-Bandes, die im obigen Excel der Summe der Spalte "Summe" entspricht.

Außerdem haben wir eine Variable "Notensumme" mit der Formel $F{Note}*$F{Summe}, auf der Ebene der Gruppe "Semester". Achten Sie drauf, dass Sie als Typ "java.lang.Double" nehmen, damit Sie keine Rundungsfehler bekommen.

Der Quotient wird dann im Textfeld gebildet, das den Notenschnitt auf Semesterebene enthält, und auf zwei Nachkommastellen gerundet:

[[Datei:JasperReports-Handbuch_notenschnitt_design2.png]]

Das Textfeld selbst muss bei "Evaluation time" den Wert "Group" haben, und bei "Evaluation group" dann den Wert der Gruppe "Semester". Und hier das Ergebnis in der Vorschau:

[[Datei:JasperReports-Handbuch_notenschnitt_vorschau.png]]

Der Wert 2,02 stimmt mit unserer manuellen Berechnung überein.


== Tabellengestaltung ==


=== Summen, Seitenzahlen ===

Um es noch ein wenig interessanter zu gestalten fügt man noch das Gehalt hinzu, summiert es für die Monate und gesamt. Dazu noch die Seitenanzahl und einen Seitenzähler und eine Überschrift.

Das Gehalt bekommt man, indem man das Gehalt aus den Feldern neben den Namen zieht. Das selbe macht man auch nochmal in das Band „Monat Group Footer 1“ und wählt hier die Aggregation „Sum“ aus, um die Summe zu erhalten.

Um einen Seitenzähler zu erhalten fügt man zunächst das Band „Page Footer“ hinzu und legt dort die Variable „PAGE_NUMBER“ ab.

[[Datei:JasperReports-Handbuch_iReport-Page_Number.jpg]]

Unter „Eigenschaften“ → „Text field properties“ → „Evaluation Time“ wählt man hier „Now“ um die aktuelle Seitenanzahl zu bekommen und „Report“ um die gesamte Seitenanzahl zu erhalten. In dem Beispiel ist die Ausgabe z.B.: „Seite 2 von 6“.


=== Seitenumbrüche steuern ===

Damit die drei Personen im Monat 2 nicht durch einen Seitenumbruch auseinandergerissen werden, gibt es einige Einstellungen in dem Band der Gruppe. Dazu einfach auf das jeweilige Band klicken, für welches die Einstellungen vorgenommen werden sollen (hier „Monat“) und dann in „Eigenschaften“ → „Group properties“ → „Keep Together“ anklicken oder wenn man möchte „Reprint header“ um den "Header" der Gruppe am Seitenkopf zu wiederholen.

Beispiel im Designermodus:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_2_Monat_Namen.jpg]]

Beispiel im Preview:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_2_1_Monat_Namen_Ergebnis.jpg]]

[[Datei:JasperReports-Handbuch_iReport-Beispiel_2_2_Monat_Namen_Ergebnis.jpg]]


=== Zeilen alternierend einfärben ===

Um nun bei mehreren Datensätzen auch noch den Überblick in den Zeilen zu behalten kann man jetzt auch noch den Hintergrund der Zeile abwechselnd farbig gestalten. Dazu Zieht man aus den „Reports Elements“ das „Rectangle“ in das „Detail 1“ Band

[[Datei:JasperReports-Handbuch_iReport-Even_Odd_2.jpg]]

und passt es der Größe des Bandes an.

[[Datei:JasperReports-Handbuch_iReport-Even_Odd_1.jpg]]

Die Hintergrundfarbe kann man nun in den Eigenschaften in „Backcolor“ ändern. Damit dies nun nicht in jeder Zeile erscheint, sondern abwechselnd, fügt man noch in den Eigenschaften in „Print When Expression“ den Wert Boolean.valueOf( $V{PAGE_COUNT}.intValue() % 2 == 0 ) ein.

Zur erläuterung:

Die Variable „PAGE_COUNT“ zählt die Anzahl der Datensätze hoch. Mit „% 2“ wird diese Variable durch 2 geteilt und nur der Restwert ausgegeben. Als Ergebnis erhält man also in jeder ungeraden Zeile eine 1. Dieses Ergebnis wird nun mit der „0“ verglichen. Wenn dieser Ausdruck/Vergleich (expression) wahr ist, wird das Objekt, in diesem Fall der Hintergrund, angezeigt. Bei diesem Ausdruck erhält also jede gerade Zeile den Hintergrund. Möchte man lieber die ungeraden Zeilen hervorheben, schreibt man einfach eine 1 anstelle der 0 hinter „==“.

[[Datei:JasperReports-Handbuch_iReport-Even_Odd_3.jpg]]

Das Ergebnis bei einer ungeraden Hervorhebung sieht z.B. so aus:

[[Datei:JasperReports-Handbuch_iReport-Even_Odd_4.jpg]]

Ein weiteres Beispiel welches bereits in der Uni Mannheim benutzt wird ist die Ausgabe einer Rechnungslegungsliste. Das Beispiel zeigt nicht nur ein aufwändigeres Layout, sondern auch, wie man gruppierte Tabellen anlegt: Dabei sind die Zeilen der Tabelle im Detail 1 Band, und die Zwischensummen in den Gruppierungs-Bändern. Die Spaltenüberschriften der Tabelle befinden sich im untersten Group-Header-Band. Im Designermodus sieht das ganze folgendermaßen aus:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_3_Uma.jpg]]

Und im Preview:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_3_Uma_Ergebnis_1.jpg]]

[[Datei:JasperReports-Handbuch_iReport-Beispiel_3_Uma_Ergebnis_2.jpg]]


=== Rahmenlinien '''vorausschauend setzen''' ===

Sowohl bei Text- als auch bei Static-Fields findet sich ein eigener Reiter zum setzen von Rahmeneigenschaften. Dort wird der Abstand des Inhaltes zum Rahmen des jeweiligen Feldes definiert, sowie Rahmenlinien gesetzt.

Beim Setzen von Rahmenlinien wird empfohlen, dass bei nebeneinanderliegenden Feldern, welche durch eine Rahmenlinie getrennt werden, jeweils in beiden Feldern Rahmenlinien gesetzt werden und nicht nur in einem der beiden Felder. Denn beim Export in das PDF-Format ist ersichtlich ob nur eines der Felder oder beide Felder Rahmenlinien besitzen. Falls dies also nicht einheitlich umgesetzt wird, erscheinen Rahmenlinien an entsprechenden Stellen dünner beziehungsweise dicker (bei Excel-Dokumenten tritt dieser Effekt nicht auf):

[[Datei:JasperReports-Handbuch_borders2.png]]


== Unterberichte ==

<blockquote>Achtung: In Edustore funktionieren Unterberichte nur, wenn der Dateiname der jrxml-Datei mit "_xmlsource.jrxml" endet. Dadurch wird dem Servlet mitgeteilt, dass die Datenquelle für den Bericht ein XML-Datenstrom ist. Dabei ist mit Performanceeinbußen zu rechnen. 
Außerdem muss beim Berichtsdesign die gleiche JasperReports Version genutzt werden wie im Server.
</blockquote>
Im folgenden eine Anleitung zur Erstellung eines Unterberichts:


=== Konfiguration des Hauptberichts ===

Erzeugen Sie für den Unterbericht mit Hilfe des [[#2.1.3.Template erzeugen|outline|Template]][[#2.1.3.Template erzeugen|outline|-Generators]] in Edustore einen leeren Bericht, und speichern Sie diesen am besten im gleichen Verzeichnis wie den Hauptbericht.

Ziehen Sie dann das Subreport-Werkzeug in den Entwurfsbereich:

Ggf.

[[Datei:JasperReports-Handbuch_subreport0_tool.png]]

Es startet der Subreport-Assistent. Hier geben Sie zunächst den Dateinamen oben an:

[[Datei:JasperReports-Handbuch_subreport1_wizard1.png]]

Im nächsten Schritt geben Sie eine Datenbank-Verbindung an. Hier wählen Sie "Don't use any connection...":

[[Datei:JasperReports-Handbuch_subreport1_wizard2.png]]

Im nächsten Schritt werden Parameter angezeigt, zu diesem Zeitpunkt gibt es aber noch keine.

[[Datei:JasperReports-Handbuch_subreport1_wizard3.png]]

Klicken Sie einfach auf "Weiter". Sie werden dann aufgefordert, einen Dateipfad für den Unterbericht zu vergeben. IReport legt diesen standardmäßig in das gleiche Verzeichnis wie den Hauptbericht. Für Edustore sollten Sie dies auch tun.

Bitte beachten Sie dass Sie beim Unterbericht nicht die *.jrxml-Datei verlinken, sondern die *.jasper-Datei, d.h. den kompilierten Report.

[[Datei:JasperReports-Handbuch_subreport1_wizard4.png]]

Danach sehen Sie einen Platzhalter für den Unterbericht im Entwurfsbereich. Beachten Sie bitte daß die Größe des Platzhalters unwichtig ist: die Ausdehnung des Unterberichts wird im Unterbericht definiert. Der Platzhalter ist lediglich wichtig, um die linke obere Ecke des Unterberichts festzulegen. 
Rechts neben dem Platzhalter sehen Sie die Eigenschaften des Unterberichts:

[[Datei:JasperReports-Handbuch_subreport2_params_none.png]]

Ein Unterbericht arbeitet meist mit Übergabe von Parametern, z.B. will man vom Hauptbericht den Inhalts des Feldes "Kostenstelle" an den Unterbericht übergeben. Dies müssen wir in den Eigenschaften des Unterberichts "deklarieren". In der Zeile "Parameters" steht nach Bedienung des Assistenten noch kein Wert. Für die Datenquelle XML gibt es außerdem einen Parameter XML_DATA_DOCUMENT, der immer übergeben werden muss: Die XML-Datenquelle des Hauptberichts. Hier eine Übersicht, welche Parameter übergeben werden:

[[Datei:JasperReports-Handbuch_subreport10_parameters.png]]

Die Zeilen mit Großschreibung sind die vorgegebenen Werte, der Parameter "Kst" speist sich aus dem JR-Feld "Kostenstelle". Das Beispiel zeigt, daß der Name für den Parameter beliebig ist.

'''Hinweis für Unterberichte mit Dezimalzahlen''': Wenn der Unterbericht mit Zahlen mit Nachkommastellen arbeitet, und Sie in JasperReports testen, dann müssen Sie noch die [[#3.1.2.Datenquelle erzeugen|outline|Parameter]] XML_LOCALE und XML_NUMBER_PATTERN wie folgt übergeben:

[[Datei:JasperReports-Handbuch_subreport2_params_number.png]]


=== Unterbericht mit Header und Footer vom Hauptbericht ===

Wenn der Unterbericht in einem normalen Gruppen- oder Detail-Band liegt, wird der Header und Footer vom Hauptbericht automatisch mitbenutzt. In vielen Fällen möchte man aber den Unterbericht nur ein mal ausgeben und legt ihn daher in das Summery-Band. Hier wird Standardmäßig der Header und Footer nicht ausgegeben oder wiederholt. Möchte man aber z.B. die Seitenzahl die im Footer liegt weiterhin angezeigt bekommen, gibt es eine Eigenschaft vom Hauptbericht, die man nur aktivieren braucht. Diese Eingenschaft nennt sich: Summary with Page Header and Footer.

Also einfach auf den Hauptbericht auswählen und in Eigenschaften diesen Punkt aktivieren.

[[Datei:JasperReports-Handbuch_subreport_header_footer.png]]


=== Konfiguration des Unterberichts ===

Nun können wir den Unterbericht öffnen, indem wir über dem Platzhalter die rechte Maustaste betätigen und "Open Subreport" wählen.

[[Datei:JasperReports-Handbuch_subreport3_open.png]]

Es erscheint ein neues Fenster mit einem leeren Entwurfsbereich. Sie könnten nun loslegen und im Detailbereich verschiedene Elemente gestaltet. Aber man muss bedenken daß ein Unterbericht für jeden Datensatz im Hauptbericht ausgeführt und eingebettet wird. Daher wird man vermutlich in den meisten Fällen im Unterbericht auf einen Filter zurückgreifen. Hier kommt dann wieder der oben genannte Parameter, z.B. "Kst" ins Spiel: Als ersten deklarieren wir den Parameter im Unterbericht, indem wir Links bei den Parametern die rechte Maustaste drücken, und "Hinzufügen..." wählen:

[[Datei:JasperReports-Handbuch_subreport4_param.png]]

Standardmäßig nennt IReport den Parameter "parameter1". Rechts können wir in den Eigenschaften des Parameters den Namen ändern, und "Use as a prompt" abwählen:

[[Datei:JasperReports-Handbuch_subreport4_param2.png]]

Weitere Änderungen sind nicht notwendig.

Wir ergänzen nun die "Report Query" [[Datei:JasperReports-Handbuch_report_query.png]] des Unterberichts von

''/ergebnisse/ergebnis/ergebniselement/sqlerg/row''

um einen Filter, der mit der Abfragesprache XPATH formuliert wird. Im obigen Beispiel würden wir jetzt nur die Zeilen der Datenquelle auswählen, wo die Nummer der Kostenstelle mit der des Hauptberichts übereinstimmt. Wir erinnern uns: letztere steht im Parameter "Kst". Anhand der vorhandenen Report Query können wir sehen, dass die Kostenstelle in den Spalten ("col") mit der id=5 steht. Der Ausdruck wird also um den Filter "''[col[@id="5"]/wert='''''$P{Kst}']''" ergänzt:

[[Datei:JasperReports-Handbuch_subreport4_query.png]]

Nun ändern wir im Entwurfsbereich des Unterberichts das Layout: für das aktuelle Beispiel wollen wir im Unterbericht eine Summe der Beträge für jede Kostenstelle ausgeben. Dazu müssen wir zunächst eine Gruppierung nach Kostenstelle hinzufügen:

[[Datei:JasperReports-Handbuch_subreport5_group1.png]]

Im Gruppierungsassistenten wählen wir das Feld "Kostenstelle" als Gruppierungsmerkmal, und im nächsten Schritt sagen wir, daß ein Gruppenkopf hinzugefügt werden soll:

[[Datei:JasperReports-Handbuch_subreport5_group2.png]]

Danach ist die Gruppierung als Band verfügbar:

[[Datei:JasperReports-Handbuch_subreport5_group3.png]]

In die Gruppierung ziehen wir dann das Feld "Summe":

[[Datei:JasperReports-Handbuch_subreport5_group4.png]]

Beim "Loslassen" des Feldes werden wir gefragt, ob wir eine Aggregatfunktion nutzen wollen; wir wählen hier die Summierung:

[[Datei:JasperReports-Handbuch_subreport5_group5.png]]

Danach ist das Feld verfügbar. Wir setzen noch das Label "Summe:" davor.

[[Datei:JasperReports-Handbuch_subreport5_group6.png]]

Den Detailbereich brauchen wir eigentlich nicht, wir können den ganz schmal machen. Danach speichern wir den Unterbericht, und gehen wieder zum Hauptbericht. Hier setzen wir den Unterbericht direkt unter das Feld "Kostenstelle":

[[Datei:JasperReports-Handbuch_subreport15_align.png]]

Danach können wir den Bericht mit der jew. Datenquelle ausführen. Das Ergebnis läßt je nach Datenmenge ein bisschen auf sich warten:

[[Datei:JasperReports-Handbuch_subreport20_erg.png]]


=== Einhängen des Berichts in Edustore ===

Damit der Bericht auch im Server nutzbar ist, muss noch folgendes eingestellt werden:

* Der Server sollte ausreichend RAM haben (Variable CATALINA_OPTS), weil hier XML als Datenquelle verarbeitet wird.
* Im Hauptbericht gibt es einen neuen Parameter SUBREPORT_DIR. Setzen Sie hier den Defaultwert ("Default value Expression" auf den Pfad, in dem die Dateien liegen (z.B. "/home/superx/webserver/tomcat/webapps/superx/WEB-INF/reports/").
* Kopieren Sie die .jasper Datei des Unterberichts in dieses Verzeichnis.
* Bei Nutzung von Versionskontrollsystemen haben Sie die *.jasper-Dateien vermutlich ignoriert (gitignore / svnignore). Sie müssen die Dateien daher mit "-f" adden / committen.

<blockquote>Vorsicht beim Einsatz von JasperSoft Studio: Die Anwendung erzeugt bei der Einzelbearbeitung eines Unterberichts nicht automatisch eine entsprechende .jasper-Datei beim Previewen des Hauptberichts (iReport machte das). Man muss also in Jaspersoft Studio im Bearbeitungsfenster oben immer "Compile Report" anklicken, um eine neue .jasper Datei zu erzeugen.
</blockquote>

== Kreuztabellen ==


=== Bedienung des Assistenten für Kreuztabellen ===

Für die Erstellung von Kreuztabellen gibt es einen eigenen Assistenten. Vorab sollte man aber zunächst ein "Summary"-Band erzeugen. Im folgenden Beispiel haben wir alle anderen Gruppierungen und Detail-Bands entfernt:

[[Datei:JasperReports-Handbuch_designer_crosstab1.png]]

Dann ziehen wir das Crosstab-Element in den Summary Band. Es erscheint der Assistent. Als Datenquelle nutzen wir die Abfrage des Berichts.

[[Datei:JasperReports-Handbuch_designer_crosstab2.png]]

Als nächsten definieren wir die Zeilendimension des Berichts:

[[Datei:JasperReports-Handbuch_designer_crosstab3.png]]

Wir wählen z.B. die Abschlüsse. Danach definieren wir die Spalten-Dimension:

[[Datei:JasperReports-Handbuch_designer_crosstab4.png]]

Wir wählen das Merkmal "Geschlecht". Danach definieren wir das Merkmal, das in den Zellen ausgegeben werden soll. Dies ist die Summe der Studierenden:

[[Datei:JasperReports-Handbuch_designer_crosstab5.png]]

Zum Schluß kann man ein Layout festlegen, und Zeilen- und Spaltensummen erzeugen:

[[Datei:JasperReports-Handbuch_designer_crosstab6.png]]

Im Entwurfsbereich erscheint ein neues Fenster mit der Kreuztabelle.

[[Datei:JasperReports-Handbuch_designer_crosstab7.png]]

Hier können wir nun Spaltenbreiten und Überschriften ändern:

[[Datei:JasperReports-Handbuch_designer_crosstab9.png]]

Das Ergebnis sieht wie folgt aus:

[[Datei:JasperReports-Handbuch_designer_crosstab8.png]]


=== Nachbearbeitung des Kreuztabellen-Assistenten ===

Der Assistent liefert nur einfache Kreuztabellen, ggf. wollen Sie diese im Nachhinein anpassen. Sie können z.B. mehr als zweistufige Hierarchien in Kreuztabellen einrichten, indem Sie im Report Inspector manuell neue Merkmale anlegen.

[[Datei:JasperReports-Handbuch_crosstab_new_row.png]]

Auch bei "Measures" können Sie neue "abhängige Variablen" anlegen, z.B. wenn Sie in einer Tabelle mit den Zeilen "Ausgaben" und "Einnahmen" die Ausgaben mit negativem Vorzeichen versehen wollen und dann saldieren wollen: Sie würden ein neues "Measure" anlegen, mit der Calculation="Sum", Typ "java.lang.Float", und der folgenden Expression bekommen alle Ausgaben ein negat. Vorzeichen:

($F{Kostenart}=="Ausgaben")?-$F{Betrag}:$F{Betrag}

Das neue Measure können Sie dann in die Zeilen- oder Spaltensummen ziehen.


=== Kreuztabellen im Gruppenfuß ===

Kreuztabellen lassen sich nicht nur im Summary Band nutzen, sondern auch in Gruppenfuß/Gruppenkopf-Bändern. Wenn Sie die Kreuztabelle z.B. in einen Groupfooter legen, müssen Sie den "Reset type“ der Gruppe anpassen. Das machen Sie indem Sie ein rechts klick auf die Kreuztabelle machen und dann auf "Crosstab data" klicken. Dort stellen Sie den "Reset type" auf "Group" und die "Reset group" auf die Gruppe in der die Kreuztabelle gelegt wurde. Wenn Sie das nicht machen funktioniert der Report nicht!


=== Kreuztabellen mit virtuellen Dimensionen ===

Sie können auch virtuelle Dimensionen in Kreuztabellen nutzen, indem Sie ähnlich wie bei der [[#2.2.4.Gruppierung ohne eigenes Band|outline|Gruppierung ohne eigenes Band]] mit Variablen arbeiten.

Um z.B. alle Studienfächer im Feld "1. Fach" auszugeben, und nur die Fächer Mathematik, Physik und Biologie zu einem Fach "Naturwissenschaften" zusammenzufassen, legen Sie eine neue Variable "fachgruppe" an, mit der Expression:

[[Datei:JasperReports-Handbuch_gruppierung_virtuell.png]]

In der Kreuztabelle können Sie nun z.B. in den Zeilen die Variable "fachgruppe" auswählen, und erhalten eine Tabelle mit der "künstlichen" Zeile "Naturwissenschaften":

[[Datei:JasperReports-Handbuch_gruppierung_virtuell2.png]]


=== Sortierung in Kreuztabellen ===

Zeilen- oder Spaltendimensionen werden in Kreuztabellen immer alphabetisch sortiert, egal wie die Sortierung in der Datenquelle ist. Das ist in der Regel kein Problem, aber wenn z.B. eine Zeilendimension anders sortiert werden soll, geht das nicht ohne weiteres. Hier ein Problembeispiel:

[[Datei:JasperReports-Handbuch_kreuztab_sortierung_falsch.png]]

Das Balkendiagramm übernimmt die Sortierung nach dem Schlüssel der Gehaltsgruppe aus der Datenquelle. In der Kreuztabelle wird die Zeilendimension "Bezeichnung der Gehaltsgruppe" angezeigt, und diese sortiert alphabetisch, was an dieser Stelle aber unsinnig ist: Der Eintrag "Kein Einkommen" sollte ganz oben stehen.

Wir schauen uns zunächst die Definition der Kreuztabelle an:

[[Datei:JasperReports-Handbuch_kreuztab_sortierung_richtig1.png]]

Die Zeilendimension sortiert aufsteigend nach Bezeichnungstext. Man kann auch keine alternative Expression als Sortierkriterium angeben. Wir müssen also einen Trick anwenden: wir nehmen den Sortierschlüssel mit in die "Bucket Expression" der Zeilendimension auf, und setzen ihn als Präfix davor:

[[Datei:JasperReports-Handbuch_kreuztab_sortierung_richtig2.png]]

Danach ist die Sortierung richtig:

[[Datei:JasperReports-Handbuch_kreuztab_sortierung_richtig3.png]]

Aber optisch ist das natürlich unschön, der Sortierschlüssel sollte am besten gar nicht angezeigt werden. Wir lösen das, indem wir den Anzeigetext wiederum so abwandeln, dass der erste Buchstabe nicht sichtbar ist. Java bietet dazu die Funktion "substring()":

[[Datei:JasperReports-Handbuch_kreuztab_sortierung_richtig4.png]]

Und siehe da: die Sortierung und Anzeige ist perfekt:

[[Datei:JasperReports-Handbuch_kreuztab_sortierung_richtig5.png]]

Dies ist nur ein Beispiel, wie man mit Hilfe von Java Expressions die Anzeige von Kreuztabellen variieren kann.


=== Parameter für Kreuztabellen ===

In Kreuztabellen hat man keinen direkten Zugriff auf die Variablen und Felder des Hauptberichts. Man kann die Werte aber als Parameter übergeben. Dazu gehen Sie wie folgt vor:

Sie machen den Parameter im Crosstab-Element bekannt, hier z.B. der Parameter "RSZ" für Regelstudienzeit):

[[Datei:JasperReports-Handbuch_crosstab_param1.png]]

Danach übergeben Sie den Parameter im Hauptbericht. Mit Rechtsklick auf das Cosstab Element können Sie eine Parameters-Map Expression hinterlegen, das ist einfach eine Zuweisung von einer oder mehreren Variablen zu jeweils einem Wert in der Groovy-Syntax mit "[Variable:Wert,...]". In dem Beispiel unten weisen wir dem Parameter "RSZ" den Wert des Feldes "RSZ" zu:

[[Datei:JasperReports-Handbuch_crosstab_param2.png]]

Danach können wir den Parameter in der Kreuztabelle nutzen, z.B. um in einer Spaltenüberschrift nur dann eine Zahl mit Soll-Kreditpunkten anzuzeigen, wenn die Fachsemester innerhalb der Regelstudienzeit liegen.

[[Datei:JasperReports-Handbuch_crosstab_param3.png]]

Und hier das Ergebnis für einen Studiengang mit 6 Semestern Regelstudienzeit:

[[Datei:JasperReports-Handbuch_crosstab_param5.png]]


=== Manuelle Kreuztabelle ===

Wenn die gewünschte Konfiguration/Einstellungen in der Kreuztabelle nicht möglich ist, kann eine Kreuztabelle mit Einschränkungen auch selber erstellt werden. Im Beispiel mit Semestern, muss vorher abgeschätzt werden wie viele Semester vorraussichtlich in den Spalten vorkommen werden. Für jedes Semester (z.B. für 10 Semester) wird dann eine Variable angelegt. Die erste bekommt das höchste Semester (wie im Screenshot zu sehen).

[[Datei:JasperReports-Handbuch_kreuztabelle_manuell_1.jpg]]

Das zweite Semester wir dann das höchste welches aber unterhalb von dem ersten liegen soll, usw.

[[Datei:JasperReports-Handbuch_kreuztabelle_manuell_2.jpg]]

Diese Semester können nun als Spalten verwendet werden mit der Option „blank when null“.


=== Layout von Kreuztabellen bearbeiten ===

Dieser Abschnitt befasst sich mit Themen zur Layoutanpassung.


==== Total einer ‚Row Group‘ entfernen ====

Wenn eine neue ‚Row Group‘ angelegt wird, wird automatisch ein dazugehöriges Total-Feld erzeugt und mit eingefügt:

[[Datei:JasperReports-Handbuch_Eingebettet_001.png|642x367px]]

Das ist in diesem Falle nicht erwünscht. Um dieses Feld zu entfernen, wird in den Properties der ‚Row Group‘ die ‚Total Position‘ = ‚none’ gesetzt:

[[Datei:JasperReports-Handbuch_Eingebettet_002.png|642x263px]]


==== Header von ‚Row Groups‘ für jede Zeile wiederholen ====

Im folgenden Screenshot ist eine Kreuztabelle dargestellt, bei welcher die Header der ‚Row Groups‘ nur einmal dargestellt werden:

[[Datei:JasperReports-Handbuch_Eingebettet_003.png|434x315px]]

Zwar ließe sich das Feld noch, so dass es bis zum nächsten ‚Row Header‘ reicht, aber in diesem Beispiel ist erwünscht, dass sich der Header für jede Zeile wiederholt:

[[Datei:JasperReports-Handbuch_Eingebettet_004.png|530x420px]]

Dazu wird die Funktion ‚Merge Header Cells‘ in den Properties der ‚Row Group‘ deaktiviert. Es kann sein, dass die Funktion einmal aktiviert und dann wieder deaktiviert werden muss, damit sie als deaktiviert erkannt wird.

[[Datei:JasperReports-Handbuch_Eingebettet_005.png|642x275px]]

Damit der Text in der ersten Spalte nicht abgeschnitten wird, wurde ‚Stretch with Overflow‘ in den Text-Field-Properties ausgewählt. Dadurch ist eine Lücke bei den anderen Spalten entstanden.

[[Datei:JasperReports-Handbuch_Eingebettet_006.png|509x404px]]

Um diese Lücke zu schließen wird der ‚Stretch Type‘ in allen folgend eingerahmten Textfeldern auf ‚Relative To Band Height (deprecated)‘ gesetzt:

[[Datei:JasperReports-Handbuch_Eingebettet_007.png|642x322px]]


==== ‚Static Field‘ und ‚Text Field‘ frei gestalten/bewegen ====

Im Default sind ‚Static Field‘ und ‚Text Field‘ in einer Kreuztabelle nicht frei positionierbar/gestaltbar. Um das zu ändern, wird im jeweiligen Bereich das Layout auf ‚Free Layout‘ eingestellt.

[[Datei:JasperReports-Handbuch_Eingebettet_008.png|642x279px]]


==== Reihenfolge der ‚Row Groups‘ ändern ====

Die Reihenfolge der ‚Row Groups‘ muss nachträglich im ‚Outline‘-Bereich geändert werden. Dies erfolgt per Drag and Drop im rot markierten Bereich:

[[Datei:JasperReports-Handbuch_Eingebettet_009.png|642x437px]]

Die Textfelder im Design-Bereich zu verschieben, reicht nicht aus, denn die ‚Row Group‘ selbst bleibt wo sie ist und dann würde nur das Textfeld in eine andere Row Group verschoben. Im folgenden Negativbeispiel wurden nachträglich im Design-Bereich die Textfelder Intervall und Datenherkunft vertauscht. Dadurch sind sie in der jeweils falschen ‚Row Group‘ gelandet:

[[Datei:JasperReports-Handbuch_Eingebettet_010.png|642x387px]]


== Diagramme ==

Um einen Bericht ansprechend zu gestalten dürfen Diagramme wie Torten- oder Balkendiagramme nicht fehlen. Diese in einen Bericht einzubringen ist auch nicht schwer.

<blockquote>Vorab sei aber darauf hingewiesen: Grafiken in JasperReports arbeiten nicht analog zu Kreuztabellen, in denen Daten nach Zeilen- oder Spaltenmerkmalen automatisch gruppiert und summiert werden. Für Grafiken sollten Sie gewährleisten, dass die Datenbasis für die Grafik '''bereits gruppiert und summiert''' sind, Sie können also keine Einzeldaten für Grafiken verwenden. Bei Datenblatt-Berichten in Edustore ist dies gewährleistet, wenn Sie im Feld "Felder" nur die Felder selektieren, nach denen in der Grafik gruppiert werden soll.
</blockquote>

=== Einfache Diagramme ===

Nehmen wir an wir haben eine Tabelle, die die Studierendenzahl mehrerer Semester nach Geschlecht aufführt. Hier ein Screenshot der Datengrundlage:

[[Datei:JasperReports-Handbuch_jaspersoft_design_query3.png]]

Die Tabelle enthält die Merkmale Geschlecht, Semester und Summe. Daraus erzeugen wir in Jaspersoft Studio (und weiter unten in iReport) ein Balkendiagramm.


==== Einfache Diagramme in JasperSoft Studio ====

Zunächst definieren wir die Sortierung der Daten. Im "Dataset and Query Dialog" sind die Felder der Datenquelle aufgeführt. Unten finden Sie den Reiter "Sorting":

[[Datei:JasperReports-Handbuch_jaspersoft_design_query2.png]]

Damit die Grafik richtig funktioniert müssen wir nach beiden Merkmalen (Semester und Geschlecht) sortieren. Das Semester sollte nicht alphabetisch nach Namen sortiert sein, sondern nach dem Zahlenschlüssel. Sonst ständen alle Wintersemester untereinander, und davor alle Sommersemester.

Dann ziehen wir aus der Palette das Chart Element in das Summary Band. Es startet automatisch ein "Chart Wizward". Hier wählen wir "Stacked Bar" als Grafiktypen:

[[Datei:JasperReports-Handbuch_jaspersoft_design_chart_wizard1.png]]

Nun müssen wir ihm sagen welches Feld die Y-Achse darstellt (hier "Summe"), und welches die X-Achse (hier "Semester der Belegung"). Das Merkmal zur Unterscheidung der Balkenfarben ("Series") ist das Geschlecht:

[[Datei:JasperReports-Handbuch_jaspersoft_design_chart_wizard2.png]]

Danach klicken wir auf "Finish", und die Grafik wird als Platzhalter im Summary Band eingefügt. Dort definieren wir noch die Breite der Grafik:

[[Datei:JasperReports-Handbuch_jaspersoft_design_chart1.png]]

Damit ist der Entwurf fertiggestellt. So sieht die Grafik aus:

[[Datei:JasperReports-Handbuch_jaspersoft_design_chart_wizard3.png]]

Es ist etwas ungünstig dass die Labels der X-Achse nicht ganz lesbar sind. Wir lösen dies mit Rotation der Labels um 45 Grad:

[[Datei:JasperReports-Handbuch_jaspersoft_design_chart_wizard4.png]]

So sieht es besser aus:

[[Datei:JasperReports-Handbuch_jaspersoft_design_chart_wizard5.png]]

Das Beispiel lädt zur weiteren Verfeinerung an.


==== Einfache Diagramme in iReport ====

Hier die Ansicht in iReports "Refresh Preview Data":

[[Datei:JasperReports-Handbuch_designer_chart2.png]]

Die Spalten der Tabelle sind selbsterklärend. Nun ziehen wir aus dem "Report Elements" die "Chart" in das Band "Summary".

[[Datei:JasperReports-Handbuch_grafik_chart_in_summary_ziehen.png]]

Dabei öffnet sich ein Fenster in dem Sie sich die Art der Grafik auswählen können. In diesem Beispiel wählen wir "Stacked Bar 3D".

[[Datei:JasperReports-Handbuch_grafik_chart_auswaehlen.png]]

Nach dem Klick auf "OK", geht es weiter mit den Inhalten der Grafik.

Als Dataset gibt es hier nur eine Auswahl.

[[Datei:JasperReports-Handbuch_grafik_dataset_auswaehlen.png]]

Daher akzeptieren wir dies mit einem Klick auf "Weiter".

Die "Series" sind die verschiedenen Unterteilungen eines Balkens. Die "Series" sind die verschiedenen Unterteilungen eines Balkens. Wir wählen hier das Merkmal "Geschlecht":

[[Datei:JasperReports-Handbuch_designer_chart3.png]].

Bei der X-Achse (in JasperReports heißt das "Category Axis") nehmen wie das Merkmal Semester, und bei der "Value expression" die Summe.

[[Datei:JasperReports-Handbuch_designer_chart4.png]]

Damit ist die Definition beendet. Wir können dann in den Eigenschaften der Grafik noch eine "Title Expression" festlegen, z.B. "Studierende nach Semester und Geschlecht". In der Vorschau sieht die Grafik so aus:

[[Datei:JasperReports-Handbuch_designer_chart5.png]]

Die Wintersemester werden noch nicht abgedruckt, dazu ändern wie die "Label rotation" auf 30°. Dies lässt die Schrift unter den Balken rotieren, damit längere Schriftzüge möglich sind.

[[Datei:JasperReports-Handbuch_designer_chart6.png]]

Wichtig für die Grafik war die Sortierung in der Datenquelle nach "dim_semester.quell_id". Mit "Series Colors" kann man die Farbe der Balken ändern etc.

<blockquote>Wenn sie jeden Balken bzw. Teil des Balkens zusätzlich mit den Werten ausgeben wollen, müssen sie in den Chart-Eigenschaften unter den "Bar*Properties" das Ankreuzfeld "Show labels" ankreuzen. Wenn es bereits angekreuzt ist, sollten Sie das Kreuz einmal entfernen und wieder setzen (Bug in iReport seit Version 4.x)
</blockquote>

=== Diagramme nach Tabelle ausgeben ===

Üblicherweise ähnelt ein Diagramm in JasperReports einer Kreuztabelle. Wenn nun ein Diagramm nach Vorgabe einer Tabelle ausgegeben werden soll, muss ein wenig getrickst werden.

Erläuterung:

In der Series expression werden die Zeilen angegeben.

In der Category expression werden die Spalten angegeben.

In der Value expression wird der Wert angegeben.

Um ein Diagramm nun zu erstellen muss pro Series + Category eine Categorie series angelegt werden und das entsprechende Feld angegeben werden.


=== Diagramme mit berechneten Werten ===

Wenn die einem Diagramm zugrunde liegende Tabelle noch Berechnungen erfordert, muss man mit Variablen arbeiten. Als Beispiel wird hier die Maske "Studierende und Studienanfänger (Zeitreihe)" benutzt. Das Ergebnis wird eine Tabelle mit Balkendiagramm der "Studierende und Studienanfänger im 1. Fachsemester (Zeitreihe)" sein.

Ein bereits fertiges Datenblatt könnte folgendermaßen aussehen:

[[Datei:JasperReports-Handbuch_grafik_datenblatt_ohne_grafik.jpg]]

Hier fehlt jetzt die Grafik, die in dem noch leeren Band "Summary" eingefügt werden soll. Wenn das Band noch nicht eingefügt wurde, einfach mit Rechtsklick auf Summary (im "Report Inspector") und dann auf "Add Band" um es anzuzeigen.

[[Datei:JasperReports-Handbuch_grafik_how_to_add_summary.png]]

Nun ziehen wir aus dem "Report Elements" die "Chart" in das Band "Summary".

[[Datei:JasperReports-Handbuch_grafik_chart_in_summary_ziehen.png]]

Dabei öffnet sich ein Fenster in dem Sie sich die Art der Grafik auswählen können. In diesem Beispiel wählen wir "Stacked Bar 3D".

[[Datei:JasperReports-Handbuch_grafik_chart_auswaehlen.png]]

Nach dem Klick auf "OK", geht es weiter mit den Inhalten der Grafik.

Als Dataset gibt es hier nur eine Auswahl.

[[Datei:JasperReports-Handbuch_grafik_dataset_auswaehlen.png]]

Daher akzeptieren wir dies mit einem Klick auf "Weiter".

Die "Series" sind die verschiedenen Unterteilungen eines Balkens. Da es in diesem Beispiel dafür keine Variable gibt, wird später noch per Hand eine Weitere hinzugefügt. Wenn es bei Ihnen möglich ist, klicken Sie rechts neben dem Feld auf den Button und fügen dort eine Variable ein. In diesem Beispiel wird als fester String "Frauen im 1. FS" eingegeben.

[[Datei:JasperReports-Handbuch_grafik_series_auswaehlen.png]]

Und dann wieder auf "Weiter".

Auf der X-Achse soll in diesem Beispiel die Semester erscheinen und auf der Y-Achse die Anzahl der Weiblichen Studierenden im 1. Fachsemester. Um dies zu erhalten wählt man als "category expression" die Variable "Semester" aus.

[[Datei:JasperReports-Handbuch_grafik_category_auswaehlen1.png]]

Dies geschieht, indem man auf den Button rechts neben dem Feld klickt,

[[Datei:JasperReports-Handbuch_grafik_category_auswaehlen2.png]]

dann doppelt auf das Feld "Semester" klickt und dann auf "Apply".

In den meisten Fällen werden hier Felder benutzt. Wenn Sie jedoch z.B. eine Variable benutzen wollen, müssen Sie nach dem Klick rechts auf den Button in dem neuen Fenster links unten z.B. auf "Variables" oder "Parameter" klicken. Dabei ändert sich der Inhalt von dem mittleren Feld.

[[Datei:JasperReports-Handbuch_grafik_category_auswaehlen3.png]]

Hier können Sie nun auch eine andere Auswahl treffen.

Das selbe gilt auch für "value expression". Der Unterschied ist hierbei, die "category expression" ist die Bezeichnung und in "value expression" dürfen nur Zahlen vorkommen, welche von JasperReports addiert werden können.

[[Datei:JasperReports-Handbuch_grafik_value_auswaehlen1.png]]

Hier wählen wir nun z.B. das Feld "1. FS Frauen" aus.

[[Datei:JasperReports-Handbuch_grafik_value_auswaehlen2.png]]

Nun noch abschließend auf Beenden drücken und wir erhalten das erste Ergebnis. Über "Preview" wird nun das Diagramm mit den Frauen aus dem 1. Fachsemester über die Semester angezeigt.

[[Datei:JasperReports-Handbuch_grafik_erstes_ergebnis.png]]

Um nun die männlichen Studenten aus dem 1. FS noch hinzuzufügen oder Änderungen an der gerade getroffenen Auswahl vorzunehmen klickt man mit der rechten Maustaste auf die Chart und dann auf "Chart Data". In dem Reiter "Details" kann man nun die eben angelegte Category bearbeiten/entfernen oder auch eine neue anlegen.

[[Datei:JasperReports-Handbuch_grafik_chart_details.png]]

Hier wollen wir jetzt noch die männlichen Studierende aus dem 1. FS noch Hinzufügen. Also klickt man auf "Hinzufügen.

[[Datei:JasperReports-Handbuch_grafik_chart_m_std_1fs_hinz.png]]

Die Eingabe funktioniert hier genau wie in dem Assistenten bei der Erstellung einer neuen Chart. Nur taucht jetzt das Problem auf, dass es kein Feld mit den Männlichen Studierenden gibt, sondern nur gesamt. Die Lösung ist aber ganz einfach. Zunächst geht man wieder in den "Expression editor" der "Value expression" und wählt das Feld "1. FS gesamt" aus, setzt dahinter ein Minuszeichen und danach wählt man noch das Feld "1. FS Frauen" aus. Jasper berechnet dann jeweils das Ergebnis und benutzt dieses als Value.

[[Datei:JasperReports-Handbuch_grafik_chart_m_std_1fs_hinz_1.png]]

Nun erhalten wir als Ergebnis folgende Tabelle:

[[Datei:JasperReports-Handbuch_grafik_zweites_ergebnis.png]]

Es gibt noch viele Änderungsmöglichkeiten unter Einstellungen wie z.B. "Label rotation" lässt die Schrift unter den Balken rotieren, damit längere Schriftzüge möglich sind und "Series Colors" um die Farbe der Balken zu ändern.

[[Datei:JasperReports-Handbuch_grafik_zweites_ergebnis1.png]]


=== Chart Customizer ===

Mit JasperSoft Studio können die über sog. "Chart Customizer" Details bzgl. des Layouts vor Diagrammen steuern. Im folgenden ein Beispiel:

Wir haben ein einfaches Balkendiagramm, in dem wir eine (automatisch) ermittelte Y-Achse mit Werten von 0-15 haben:

[[Datei:JasperReports-Handbuch_jr_chart_customizer_range1.png]]

Nun wollen wir den Bereich auf 12 (in 2er-Schritten ändern). Man könnte dies ganz leicht über die Eigenschaften ändern:

[[Datei:JasperReports-Handbuch_jr_chart_customizer_range2a.png]]

Hier kann man aber nicht die Schrittweite ändern. Wir legen dazu einen Chart Customizer vom Typ "Value Axis Range and Tick" an:

[[Datei:JasperReports-Handbuch_jr_chart_customizer_range2.png]]

und damit sieht das Diagramm so aus:

[[Datei:JasperReports-Handbuch_jr_chart_customizer_range3.png]]

Die Y-Achse zählt nun in 2er Schritten von 0 bis 12.

<blockquote>Noch ein Hinweis: Bei Y-Achsen mit kleinen Wertebereichen kann es vorkommen, dass JR die Y-Achse automatisch mit Intervallen mit Nachkommastellen versieht, also z.B. 1 - 1,5 - 2 - 2,5 etc. Bei manchen Maßen macht die Nachkommastelle keinen Sinn (z.B. wenn Studierende gezählt werden). Um das zu ändern gehen Sie in der Eigenschaften der Y-Achse (Chart → Value axis) und setzen bei der Eigenschaft "Value axis tick label mask" den Wert "#" (Pattern für ganzzahlig) ein. Damit wird nur noch ganzahlig hochgezählt.
</blockquote>

=== Balken Labels ===

In Balkendiagrammen können die exakten Zahlen nicht genau ermittelt werden. Aus diesem Grund wird oft gewünscht, die Zahlen noch mal schriftlich darzustellen.

[[Datei:JasperReports-Handbuch_balken_labels_1.png]]

Um die Zahlen anzeigen zu lassen muss einfach in den Chart Properties unter Advanced „Common Chart Properties → Plot → Show Labels“ auf true gesetzt werden.


== Booklets ==

Ab JR 6.2 oder höher (d.h. SuperX-Kernmodul 4.8 oder HISinOne-BI 2018.12) gibt es die Möglichkeit, Berichts-"Bücher" mit Deckblatt, Inhaltsverzeichnis und Schlußseite zu erstellen. Die Erstellung ist übersichtlicher als eine Kombination aus Haupt- und Unterbericht, und bietet beim Seitenlayout mehr Optionen, z.B. kann man in einem Booklet Hoch- und Querformat kombinieren.

Englische Anleitungen siehe

https://community.jaspersoft.com/documentation/tibco-jaspersoft-studio-user-guide/v60/report-books

Wg. der Version ist diese Möglichkeit in iReport nicht mehr verfügbar, Sie müssen JasperSoft Studio nutzen. Wenn Sie dort mit File -> New einen neuen Report erzeugen, können Sie bei Report type den Wert "Book report" wählen. Der Assistent fragt Sie dann, ob Sie Deckblatt, Inhaltsverzeichnis und die Schlußseite benötigen, kreuzen Sie die jew. Position an. Sie erhalten danach ein Entwurfsfenster mit dem Hauptbericht, der drei Abschnitte enthält: Das Deckblatt und Inhaltsverzeichnis ("Cover and table of contents"), den Buchinhalt ("Content") und die Schlußseite ("Backcover"):

[[Datei:JasperReports-Handbuch_booklet_main1.png]]

Wenn Sie die Datei speichern, werden die jew. Unter-Dateien automatisch mit angelegt, mit dem Zusatz "*_cover.jrxml", "*_toc.jrxml" und "*_backcover.jrxml".


=== Hauptbericht im Booklet ===


==== Aufbau des Hauptberichts ====

Startpunkt beim Booklet ist der Hauptbericht. Dieser hat keine "Bänder" im Sinne einer Ergebnisausgabe, insbesondere gibt es kein Detailband. Trotzdem arbeitet der Hauptbericht mit einer Datenquelle im Sinne eines Detailbandes, hier heißt das Band "Content". Für Makroberichte in SuperX-/BI müssen wir für alle Unterberichte dieselbe XML-Quelle verwenden, d.h. wir müssen im Hauptbericht genau eine Zeile der XML-Quelle filtern. Wir machen das mit XPATH mit dem Ausdruck 

/ergebnisse/ergebnis[@ordnr='0']/ergebniselement/sqlerg/row[@no='0']

Dies liefert die erste Zeile der ersten Tabelle des Makroberichts im Ergebnis.

Klicken Sie also oben auf die Datenquelle des Hauptberichts, und fügen Sie den Filter ein:

[[Datei:JasperReports-Handbuch_booklet_main2.png]]

Die Funktion „Read Fields“ funktioniert in diesem Fall nicht. Die Felder für den Hauptbericht werden manuell in den Sourcecode eingefügt. Dazu erstellen Sie zunächst, wie in [[#4.5.Makroberichte als Datenquelle für JasperReports|outline|Abschnitt 4.5]] beschrieben, ein JR-Template für den Makrobericht. Aus diesem Template kopieren Sie aus dem Sourcecode die Felder und fügen diese im Booklet ein. Fügen Sie alle Felder sowohl im Haupt- als auch in den Unterberichten des Booklets ein.

Im Content Band können Sie dann mit der rechten Maustaste die jew. Unterberichte verlinken. Die Technik ist identisch mit den normalen Haupt/-Unterberichten, nur dass das Seitenlayout nicht vom Hauptbericht zum Unterbericht vererbt wird.

Im Beispiel haben wir einen Unterbericht verlinkt:

[[Datei:JasperReports-Handbuch_booklet_main3.png]]

Im Feld "Component Expression" geben Sie den Unterbericht an. Im Feld "Tab name expression" können Sie den Namen des TABs in Excel definieren. Standardmäßig wird bei einem Booklet beim Export nach Excel also ein Arbeitsblatt mit mehreren Sheets.

Der Unterbericht wird mit den gleichen Parametern aufgerufen wie bei klassischen [[#2.5.1.Konfiguration des Hauptberichts|outline|Unterberichten]]. Der erste Unterbericht bekommt die ordnr 0, der zweite Unterbericht die ordnr 1 usw.:

[[Datei:JasperReports-Handbuch_booklet_main4.png]]


=== Übergabe von Layouts vom Hauptbericht an Unterberichte ===

Generell werden im Booklet keine Layoutvorgaben vom Hauptbericht an den jew. Unterbericht übergeben. Ausnahme: Die Property "net.sf.jasperreports.export.xls.detect.cell.type", die beim Excel Export als Zahl formatierte Zellen auch in Excel als Zahl ausgibt, wird im Hauptbericht gesetzt und dann an die Unterberichte übergeben.

Achtung: Je nach JasperSoft Studio Version kann man diese Property nicht in der graphischen Entwcklungsumgebung setzen, sondern nur im *.jrxml-Quellcode.


=== Booklet Deckblatt ===

Das Deckblatt ist ein normaler JasperReport mit Elementen im Titel-Band. Beachten Sie dass im Unterbericht auch Seitenränder und Seitenformate definiert sein müssen. Sie können auch vom Hauptbericht Parameter übergeben, hier z.B. das Semester:

[[Datei:JasperReports-Handbuch_booklet_cover1.png]]

Im Hauptbericht wiederum wird dieser Parameter dann übergeben, hier z.B. aus der Legende der Maske:

[[Datei:JasperReports-Handbuch_booklet_cover2.png]]


=== Booklet Inhaltsverzeichnis ===

Das Inhaltsverzeichnis ist ein Bericht ohne Datenquelle, und bekommt über die Evaluation Time="Report" die Anweisung, die Inhaltsdokumente nach Lesezeichen (HTML-Anchors) zu durchsuchen.

[[Datei:JasperReports-Handbuch_booklet_toc1a.png]]

Die Datenquelle ist leer, und über die Property

net.sf.jasperreports.bookmarks.data.source.parameter=REPORT_DATA_SOURCE

wird als Datenquelle der Content angegeben.

[[Datei:JasperReports-Handbuch_booklet_toc1b.png]]

Das Berichtsdesign ist vom Assistenten vorgegeben und relativ einfach. Sie können bis zu drei Ebenen für das Inhaltsverzeichnis angeben, jede Ebene benötigt ein eigenes Detailband.

[[Datei:JasperReports-Handbuch_booklet_toc2.png]]

Die Feldnamen im Bericht sollten nicht geändert werden. Sie können aber das Layout anpassen.


=== Booklet erster Detailbericht ===

Der Detailbericht ist ein normaler Unterbericht, d.h. er hat den Parameter "ordnr":

[[Datei:JasperReports-Handbuch_booklet_content1.png]]

Die Variable "ordnr" wird dann bei der Datenquelle des Unterberichts ausgewertet:

[[Datei:JasperReports-Handbuch_booklet_content2.png]]

Der Unterbericht soll sicherlich auch Seitenzahlen anzeigen, dazu fügen Sie noch ein "Page footer" Band hinzu, und erzeugen dort ein Textfeld mit dem Inhalt z.B.

"Seite "+$V{MASTER_CURRENT_PAGE}

Das Textfeld muss bei Evaluation time den Wert "Master" haben.

[[Datei:JasperReports-Handbuch_booklet_content3.png]]

Danach wird die Seitenzahl jedes Unterberichts an den Hauptbericht angepaßt.

Für das Inhaltsverzeichnis müssen Sie im jew. Detailbericht Lesezeichen (HTML-Anchors) und jeweils eine Ebene angeben. Wir können z.B. für das Textfeld der Überschrift einen Anker der Ebene 1 festlegen:

[[Datei:JasperReports-Handbuch_booklet_content4.png]]

Danach legen wir für das Gruppenband für das Textfeld mit dem Label der Gruppe (Fakultätsname) einen Anker der Ebene 2:

[[Datei:JasperReports-Handbuch_booklet_content6.png]]


=== Das fertige Booklet ===

So sieht das Booklet im Preview im JasperSoft Studio aus: Zuerst das Deckblatt...

[[Datei:JasperReports-Handbuch_booklet_preview1.png]]

... und dann auf Seite 2 das Inhaltsverzeichnis:

[[Datei:JasperReports-Handbuch_booklet_preview1b.png]]

und dann auf Seite 3 der erste Unterbericht:

[[Datei:JasperReports-Handbuch_booklet_preview2.png]]


== Schriften ==


=== Allgemeines zu Schriften ===

Für den Entwurf von Berichten ist es wichtig, daß die jew. Schriftart auch beim Server-System und beim Client verfügbar sind.

<blockquote>Ein häufiger Fallstrick ist hier: unter Windows wird mit JasperReports entworfen, und dort z.B. die Schriftart "Arial" gewählt. Der Report soll auf dem Server unter Linux laufen, dort gibt es die Schriftart nicht. Resultat: der Bericht ist nicht kompilierbar.
</blockquote>
Bei PDF-Dateien lassen sich Fonts ggf. auch in die Datei einbetten, bei Exportformaten wie OpenOffice oder Word ist dies nicht möglich. Sie sollten daher Schriftarten wählen, die auch beim Client mit größter Wahrscheinlichkeit installiert sind. Die sicherste Wahl ist es, Font-Familien anzugeben, z.B. "Serif".

Im Zweifelsfall installieren Sie die Schriftart auf allen beteiligten Systemen. TrueType Fonts lassen sich in JasperReports importieren und nutzen, sie können sogar in PDF-Dateien standardmäßig eingebettet werden. Im folgenden wird die Schriftart "Liberation Sans" installiert, die man auf [https://fedorahosted.org/liberation-fonts/ https://fe][https://fedorahosted.org/liberation-fonts/ dorahosted.org/liberation-fonts/] herunterladen kann. Entpacken Sie das Download Paket in einem beliebigen Verzeichnis.


=== Schriften in iReport einbinden ===

Achtung: wenn Sie iReport unter Windows nutzen, müssen Sie für die folgenden Schritte iReport als Admin starten:

Im Menü "Extras"->"Optionen" können Sie den Font importieren:

[[Datei:JasperReports-Handbuch_font_import_step1.png]]

Wählen Sie aus der Dateiliste zunächst den "Regular"-Font aus, z.B. die Sans-Serif-Variante. Im nächsten Schritt geben Sie dem Font einen Namen, und Sie wählen die zugehörigen Dateien für Fettdruck etc:

[[Datei:JasperReports-Handbuch_font_import_step2.png]]

Außerdem kreuzen Sie an, daß der Font in die jew. PDF-Datei eingebettet wird. Die nächsten zwei Dialoge (Locales, Font Mappings) lassen wir der Einfachheit halber erstmal weg. Wenn Sie dann OK drücken, ist der Font in iReport installiert. Sie können die Einstellungen jederzeit ändern, indem Sie auf "Edit Font" klicken:

[[Datei:JasperReports-Handbuch_font_import.png]]

Hier die Ansicht, wenn Sie auf "Edit Font" klicken:

[[Datei:JasperReports-Handbuch_font_import1.png]]

Am Ende des Formulars können Sie noch PDF-Exportoptionen wählen, z.B. ob die Schriftart in PDF-Dateien eingebunden werden soll. Achtung: beachten Sie lizenzrechtliche Fragen, die wenigsten Fonts sind ohne weiteres kopierbar. Wir empfehlen den Liberation-Font, der steht unter der OpenSource Lizenz GPL.


=== Schriften in '''JasperSoft Studio''' einbinden ===

Unter „Window“ → „Preferences“ können Sie Fonts einbinden:

[[Datei:JasperReports-Handbuch_font_import4.png]]

Nach einem Klick auf „Add“ öffnet sich ein neues Fenster. Dort geben Sie dem Font einen Namen und wählen die zugehörige Datei für den normale Ausführung des Fonts. Es gibt weitere Reiter für Bold, Italic und Bold Italic:

[[Datei:JasperReports-Handbuch_font_import5.png]]

Außerdem kreuzen Sie an, daß der Font in die jew. PDF-Datei eingebettet wird. Die nächsten zwei Dialoge (Locales, Font Mappings) lassen wir der Einfachheit halber erstmal weg. Wenn Sie dann OK drücken, ist der Font in iReport installiert.

Sie können die Einstellungen jederzeit ändern, indem Sie auf "Edit Font" klicken:

[[Datei:JasperReports-Handbuch_font_import6.png]]

Achtung: Beachten Sie lizenzrechtliche Fragen, die wenigsten Fonts sind ohne weiteres kopierbar. Wir empfehlen den Liberation-Font, der steht unter der OpenSource Lizenz GPL.


=== Default-Schriftart in iReport ===

Sie können die Default Schriftart in iReport einstellen:

[[Datei:JasperReports-Handbuch_ireport_default_font.png]]

Stellen Sie den Default-Font auf "Liberation Sans". Danach müssen Sie iReport neu starten.


=== Fonts auf dem Server ===

Um Schriftarten auf einen Tomcat-Server zu installieren, müssen die vier ttf-Dateien (normal, fett, kursiv, fett-kursiv) in den Ordner $JRE_HOME/lib/fonts kopiert werden. Für alle Java Anwendungen wie den Tomcat und JasperReports stehen dann die in dem verwendetem Java zur Verfügung.

Beispiel Arial unter Ubuntu 18.04:

Prüfen Sie mit dem Kommando

ps fax | grep tomc

welcher Tomcat läuft. Sie bekommen eine Ausgabe z.B.

47769 ? Sl 36:25 /usr/lib/jvm/java-8-openjdk-amd64/bin/java -Djava.util.logging.config.file=/var/lib/tomcat8/conf/logging.properties -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Djdk.tls.ephemeralDHKeySize=2048 -Djava.protocol.handler.pkgs=org.apache.catalina.webresources -Xmx3500M -XX:MaxPermSize=400m -Djava.awt.headless=true -Dfile.encoding=UTF-8 -DSuperX-DB-PROPERTIES-SET=true -Djava.endorsed.dirs=/var/lib/tomcat8/endorsed -classpath /var/lib/tomcat8/bin/bootstrap.jar:/var/lib/tomcat8/bin/tomcat-juli.jar -Dcatalina.base=/var/lib/tomcat8 -Dcatalina.home=/var/lib/tomcat8 -Djava.io.tmpdir=/var/lib/tomcat8/temp org.apache.catalina.startup.Bootstrap start

Der erste Befehl zeigt den Pfad zu JRE_HOME, also /usr/lib/jvm/java-8-openjdk-amd64. Sie kopieren also die Dateien z.B.

arial.ttf

arialbd.ttf

arialbi.ttf

ariali.ttf

von

C:\Windows\winsxs\amd64_microsoft-windows-font-truetype-arial_31bf3856ad364e35_6.1.7601.17514_none_d0a9759ec3fa9e2d\*.ttf

nach

/usr/lib/jvm/java-8-openjdk-amd64/lib/fonts

und starten dann Tomcat neu.

<blockquote>Achtung: Sorgen Sie dafür dass Sie eine Lizenz für die jew. Fonts haben, weil diese bei PDF in die ausgelieferten Dateien eingebettet werden.
</blockquote>

=== Font Extension ===

Eine Alternative zu dem Einbinden der Schriftart über das Java Verzeichnise Font Extension. Diese hat aber nicht immer funktioniert. Um auf diesem Wege die Fonts auf einem Ziel-Server einzubinden, kann man die Schriftart als Font Extension exportieren, die dann wiederum in den CLASSPATH des Servers (bei Webanwendungen WEB-INF/lib) kopiert werden müssen:

[[Datei:JasperReports-Handbuch_font_import2.png]]

Nutzen Sie dazu den obigen Button "Export as extension", und wählen Sie einen Dateinamen mit der Endung ".jar".

<blockquote>Hinweis: Die Einbettung einer Font Extension in einer JasperReports-Laufzeitumgebung klappt erst mit JasperReports 3.7.2 oder höher.
</blockquote>
Wenn Sie in iReport auch PDF als Vorschau wählen, erzeugt iReport im Verzeichnis der jrxml-Datei auch eine entsprechende PDF-Datei. Damit diese die Fonts enthält, müssen Sie auch in iReport im CLASSPATH die Font-Extension einbinden. In diesem Falle ist es vorteilhaft, die Endung ".jar" (nicht ".zip") zu wählen, weil iReport hier nur jar-Dateien einbindet.

Noch ein Hinweis zu den Attributen "PDF Font name" und "PDF Encoding":

[[Datei:JasperReports-Handbuch_font_import3.png]]

Diese Attribute werden nicht mehr ausgewertet, wenn Sie mit Font Extensions arbeiten.


== TextField-Formatierung ==

In diesem Abschnitt werden verschiedene Einstellungen und Möglichkeiten der Formatierung in TextFields vorgestellt und erläutert.


=== Ausgabe von '''NULL''' als '''String''' verhindern ===

Falls NULL in einem TextField als String ausgeschrieben wird, kann dies verhindert werden, indem die Einstellung „Blank When NULL“ aktiviert wird. Das Feld bleibt dann leer:

[[Datei:JasperReports-Handbuch_text_field_formatting.png]]


=== Einzelne Wörter unterstreichen oder fett drucken ===

Wenn in einem TextField einzelne Wörter unterstrichen oder fett gedruckt werden sollen, einfach in den „Text properties“ unter „Markup“ „styled“ auswählen. In dem Textfield dann einfach um das zu unterstreichende Wort „ … “ schreiben oder „ … “ um es fett gedruckt auszugeben.

<blockquote>Bitte beachten, dass die PDF-Preview aus Jaspersoft Studio heraus keinen Fettdruck darstellt.
</blockquote>

=== Zahlen- und Datumsformat ===

Die Formatierung der Werte kann mit Hilfe des Attributes "Pattern" gesetzt

werden. Hier ein Beispiel:

[[Datei:JasperReports-Handbuch_textfield_pattern1.png]]

Das Textfeld bekommt das Pattern "0", d.h. es wird eine Ganzzahl inkl. 0 angezeigt. Der Platzhalter "#" steht für Zahlenbestandteile, hier wird eine 0 allerdings nicht angezeigt. Weitere Zahlen- und Datumsformate sind im Assistenten (linker Teil des Screenshots) sicher selbsterklärend.


=== Pattern Expression ===

Hat man pro Spalte / Zelle unterschiedliche Werte z.B. Datumsangaben und Währungseinheiten

oder Ganzzahlen und Kommazahlen und möchte diese unterschiedlich formatieren, so kann dies

mit dem Attribut "Pattern Expression" dargestellt werden.

Hier ein Beispiel für die Ausgabe von Ganzahlen und Kommazahlen:

$V{valueMeasure}.doubleValue() == Math.floor($V{valueMeasure}.doubleValue()) &&

!Double.isInfinite($V{valueMeasure}.doubleValue()) ?

"#0;#0" : "###0.00;###0,00"

Hier der Pattern Expression Editor:

[[Datei:JasperReports-Handbuch_ireport_pattern_expression_editor.png]]

Hier das Ergebnis:

[[Datei:JasperReports-Handbuch_ireport_pattern_expression_ergebnis.png]]


== Effiziente Formatierung ==

Wenn Sie keine Lust haben, jedes Textelement eines Berichts einzeln zu formatieren, empfehlen wir als ersten Schritt, Formatierungen zu kopieren.

Im Kontextmenü jedes Elements gibt es die Menüpunkte "Copy Format" und "Paste Format", die jeweils Formate kopieren und einfügen.

[[Datei:JasperReports-Handbuch_copy_format.png]]

Für Hochschulen ist ein einheitliches Layout der Berichte wichtig, und so bietet es sich an, zentrale Layouts zu definieren und dann wiederzuverwenden. In JasperReports heißen Layouts auch "Styles" bzw. Formatvorlagen. Ähnlich wie in OpenOffice Writer oder MS Word lassen sich Formatvorlagen definieren und zuweisen. Bei Änderungen der Formatvorlage werden diese Änderungen auf alle Elemente automatisch übertragen - auch nachträglich.

In der "Styles Library" werden z.B. einige häufig verwandte Layoutvorlagen angeboten.

[[Datei:JasperReports-Handbuch_styles_library.png]]

Sie können die Formate anwenden, indem Sie einfach die jew. Vorlage von der "Styles Library" per Drag and Drop auf das Ziel-Textfeld im Report Design ziehen und somit anwenden.

Sie können auch eigene Formatvorlagen zentral definieren. Im Menü Datei->New->Style geht es los: Wir erzeugen z.B. eine neue Style-Datei mit dem Namen "meinLayout.jrtx":

[[Datei:JasperReports-Handbuch_style_def_folie.png]]

In der jrtx-Datei definieren sie einen oder mehrere Formatvorlagen. Wir definieren z.B. die Formatvorlage "Textelemente", und geben ihr die Eingenschaft "SansSerif, Schriftgröße 12".

Danach können sie die Datei in der jrxml-Datei im Report Inspector unter "Styles" einbinden. Damit sind die Formatvorlagen in dieser Datei verfügbar, und können bei den Elementeigenschaften im Attribut "Style" zugewiesen werden:

[[Datei:JasperReports-Handbuch_styleref_design_folie.png]]

JasperReports nimmt standardmäßig den absoluten Pfad der jrtx-Datei, in der XML-Quelle sollten Sie diesen Pfad auf relativ umstellen.


== Conditional styles – '''Bedingte Formatierung''' ==

Wenn man in einzelne Textfelder "bedingte Formatierung" nutzen will (z.B. farbiger Hintergrund, Fettdruck), hat man früher mehrere Textfelder einzeln angelegt, mit dem gleichen Inhalt und einer jeweiligen "Print-when expression". Das geht seit JR 3.x eleganter mit den sog. "Conditional styles".

Hierfür wird ein Style angelegt und diesem diverse „Conditional Styles“ untergeordnet. Die „Conditional Styles“ enthalten Bedingungen und Formatierungseinstellungen. Der Style kann beispielweise einem Textfeld übergeben werden. Sobald die Bedingung eines „Conditional Styles“ erfüllt wird, werden die im „Conditional Style“ festgelegten Formatierungseinstellungen auf das Textfeld angewandt. Die Einstellungen im Textfeld selbst werden allerdings höher priorisiert. Eine detaillierte Erläuterung der Priorisierung anhand eines Beispiels findet sich in Abschnitt „Textfeld vs. Conditional Style – Priorisierung“


=== Beispiel in JasperSoft Studio – Schrift fett machen ===

Zunächst legen Sie die Formatierungen an, indem Sie unter Styles die rechte Maustaste drücken und über „Create Style“ einen Style erstellen, beispielsweise '''Daten_angepasst'''.

[[Datei:JasperReports-Handbuch_cond_style3.png]]

Durch Rechtsklick auf '''Daten_angepasst''' wird über „Create Conditional Style“ ein neuer Conditional Style hinzugefügt. Es erscheint ein neuer Unterknoten <No condition set>. Über die Properties können anschließend die zu erfüllende Bedingung als Expression, beispielsweise

''$F{Name}.equals("Summe Aktiva")||$F{Name}.equals("Summe Passiva")''

festgelegt und die Formatierungseinstellungen vorgenommen werden. In diesem Falle ist Fettschrift (bold) gewählt :

[[Datei:JasperReports-Handbuch_cond_style4.png]]

Um den Style inklusive seiner Conditional Styles auf beispielsweise ein Textfeld anzuwenden, werden die Properties des entsprechenden Feldes geöffnet. Im Reiter Appearance wird der gewünscht Style, in diesem Falle '''Daten_angepasst''',''' '''dem Textfeld zugeordnet:

[[Datei:JasperReports-Handbuch_cond_style5.png]]

Bei mehreren conditional styles wird die Reihenfolge ausgewertet, alle zutreffende conditional styles werden genommen. Die Reihenfolge wird direkt im XML oder per Drag&Drop geändert.

Es kam in der Vergangenheit bereits zu dem Phänomen, dass im Conditional Style Fettschrift gewählt war, aber nicht ins Textfeld übernommen wurde, während beispielsweise Kursivschrift problemlos und wie erwartet funktionierte. Eine genauere Beschreibung und Lösung findet sich im Abschnitt „Textfeld vs. Conditional Style – Priorisierung“


=== Beispiel in iReport – Schrift fett machen ===

Um z.B. einzelne Zeilen nach einer Bedingung fett zu machen oder nicht kann man so vorgehen: Zunächst legen Sie die Formatierungen an, indem Sie im Report Inspector unter Styles die rechte Maustaste drücken und ein Style hinzufügen, z.B. '''zw_maybe_bold''' für einen Style der Fett sein soll, wenn im Feld '''zw''' bestimmte Werte stehen.

[[Datei:JasperReports-Handbuch_styles.png]]

Danach erzeugen Sie mit Rechtsklick auf '''zw_maybe_bold''' eine neue Bedingung mit „Hinzufügen von Conditional Style“. Bei dem neuen Unterknoten <No condition set> klicken Sie auf die rechte Maustaste, dann Edit Condition. Hier können Sie wie gewohnt eine Bedingung in Form einer Expression eingeben, z.B.

$F{Zweckbestimmung}.equals("Gesamtausgaben")||$F{Zweckbestimmung}.equals("Gesamteinnahmen")

Dann müssen Sie den neuen Conditional Style anklicken

[[Datei:JasperReports-Handbuch_cond_style.png]]

und in den Eigenschaften bold auf true setzen.

Dann wählt man im Report designer die Felder aus, die ggfs. fett dargestellt werden sollen, und bei den Eigenschaften als Style '''zw_maybe_bold'''.

[[Datei:JasperReports-Handbuch_cond_style2.png]]

Wenn man mit Padding arbeiten will, kann man für den Style padding angeben, muss aber anscheinend manuell im jrxml leftpadding entfernen

<box topPadding="0" <s>leftPadding="0"</s> bottomPadding="0">

Bei mehreren conditional styles wird die Reihenfolge ausgewertet, alle zutreffende conditional styles werden genommen. Es gibt zwar einen Menüpunkt „Reihenfolge ändern“ bei rechtem Mausklick, der ist jedoch deaktiviert, man kann die Reihenfolge aber direkt im XML ändern oder per Drag&Drop.

Leider kann man nicht einen conditionalstyle auf ein leere Zelle anwenden (z.B. Unterstrich), wenn man Excelexport macht, wird daraus einfach eine leere Zelle ohne Formatierung selbst wenn man Leerzeichen in der Text Expression hat.

Werden Variablen im conditional style verwendet, muss die evaluation time aktiviert werden über die property:

<property name="net.sf.jasperreports.style.evaluation.time.enabled" value="true"/>

Siehe https://community.jaspersoft.com/blog/tip-data-set-variable-usage-conditional-style-table-component-jasper-reports

Ein Style kann auch mit einem anderen Style verknüpft werden, indem in dem entsprechenden Style unter dem Reiter „Style“ in dem Feld „Style“ das entsprechende Style ausgewählt wird. Somit können bestimmte Wiederholungen gespart werden.


=== Textfeld vs. Conditional Style – Priorisierung ===

In diesem Abschnitt wird anhand eines Beispiels aufgezeigt, dass Textfelder höher priorisiert sind als Conditional Styles und welche Fallstricke dadurch entstehen können. Das Beispiel:

Einem Textfeld wird ein Style zugeordnet, der einen Conditional Style enthält, welcher bei erfüllter Bedingung den Text fett und kursiv darstellen soll:

[[Datei:JasperReports-Handbuch_cond_style6.png]]

Im Textfeld selbst sind beide Einstellungen deaktiviert:

[[Datei:JasperReports-Handbuch_cond_style7.png]]

Das Ergebnis ist, dass im Bericht der Text dieses Feldes zwar kursiv, aber nicht fett dargestellt wird. Zum Testen werden weitere Formatierungseinstellungen im Conditional Style hinzugefügt, beispielsweise Unter- und Durchstreichen und auch dies wird umgesetzt. Die Bedingung des Conditional Styles ist also erfüllt.

Der Grund für dieses Verhalten ist nur mit Blick auf den Source-Code ersichtlich:

[[Datei:JasperReports-Handbuch_cond_style8.png]]

Dort findet sich in den Einstellungen des Textfeldes ''isBold=“false“''. Dieses Fragment ist dadurch entstanden, dass in der Designoberfläche von JasperSoft Studio für das Textfeld die Einstellung bold einmal aktiviert und dann wieder deaktiviert wurde. Im Source-Code wird nach dem ersten Aktivieren ''isBold=“true“'' hinzugefügt und beim Deaktiveren nicht wieder komplett entfernt, sondern auf false gesetzt. Da die Einstellungen im Textfeld selbst höher priorisiert werden, als jene der Conditional Styles, wird der Fettdruck des Conditional Styles nicht umgesetzt. Löscht man im Source-Code das Fragment ''isBold=“false“'', dann wird der im Conditional Style definierte Fettdruck umgesetzt.


=== Default Style ===

Es ist möglich einen Style als Default Style zu verwenden. Hierfür wird beim Style, nicht beim Conditional Style, die entsprechende Einstellung gesetzt:

[[Datei:JasperReports-Handbuch_cond_style9.png]]

Dieser Style wird nun auf jedes Feld angewandt, dem kein anderer Style zugeordnet ist.


== Expression Editor ==

Im Expression Editor werden die für die Ausgabe bestimmten Werte angegeben. Zahlen werden ohne Zusatz eingetragen. Feste String Werte werden zwischen Anführungszeichen gesetzt. Felder und Variablen können über ein Doppelklick auf den jeweiligen Namen unterhalb des Eingabefeldes eingefügt werden.

[[Datei:JasperReports-Handbuch_ireport_filter1.png]]

Zu den Feldern und Variablen gibt es auch noch Funktionen in dem 3. unterem Kästchen.

Ein Beispiel für Textausgabe:

Es soll ausgegeben werden „Auswertungszeitraum 1.1.<<Jahr>> bis 31.12.<<Jahr>>“.

Anstatt zwei statische Textfelder und zwei dynamische zu machen, legt man eine Expression an:

"Auswertungszeitraum: 1.1."+$F{legende_Jahr_value}+" bis 31.12."+$F{legende_Jahr_value}

<blockquote>Der Clou an JasperReports ist: da das Programm auf der Programmiersprache Java beruht, kann man in Expressions echten Java Code einfügen bzw. um eigenen Java Code erweitern. Wenn Sie z.B. wissen dass das benutzte Feld "$F{Lehr- und Forschungsbereich}" vom Typ String ist, können Sie alle in Java eingebauten String Funktionen benutzen, z. B. Substring, contains, indexOf, toLowerCase etc. Analog auch für andere Datentypen.
</blockquote>

=== Bedingungen ===

Bedingungen sind in dem Expression Editor auch möglich. Wenn z.B. eine Variable nur Ausgegeben werden soll, wenn der Wert größer, kleiner oder gleich einem anderem vorgegebenen Wert oder Variable sein soll, wird folgende Syntax verwendet:

<<Bedingung>> ? <<Ausgabe wenn Bedingung wahr>> : <<Ausgabe wenn Bedingung falsch>>

Bedingungen:

String1 == String2

String1 != String2

Nummer1 > Nummer2

String1.contains( String2 )

String1 == null

usw.

Wie oben angegeben: Wenn die Bedingung wahr ist, wird der Wert nach dem Fragezeichen genommen. Wenn die Bedingung falsch ist, wird der Wert nach dem Doppelpunkt genommen.


=== Umgang mit Zeichenketten ===

Häufig werden für Berichtsausgaben Zeichenketten manipuliert. Dadurch, daß JasperReports innerhalb der Java-Runtime läuft, stehen uns mächtige Methodenaufrufe zur Verfügung, die in Java schon eingebaut sind.

Für Zeichenketten hier eine Übersicht:

http://docs.oracle.com/javase/7/docs/api/java/lang/String.html


=== Umgang mit Datumsfeldern ===


==== Datumswerte aggregieren ====

Fürs Berichtsdesign auf aggregierter Ebene ist es oft praktisch, Datumswerte auf "grobere" Kategorien zu aggregieren, z.B. Monate, Quartale, oder Jahre. Um solche Werte auszugeben bzw. danach zu gruppieren können Sie eigene Variablen anlegen, die dann im Expression Editor mit Hilfe von Java berechnet werden. Hier ein Beispiel für eine Transformation vom Datum zur Einheit "Jahr-Monat":

(($F{Datum}.getYear()+1900)*100)+($F{Datum}.getMonth()+1)

Wenn wir annehmen, dass im Feld "Datum" ein Datums- oder Zeitstempel-Wert steht, dann wird über die o.g. Expression daraus ein Zahlenwert nach dem Muster Jahr (vierstellig) + Monat (zweistellig), z.B. für den 13.5.2013 würde daraus der Wert 201305. Nach diesem ganzzahligen Wert kann man dann sortieren und gruppieren.

<blockquote>Anmerkung: die o.g. Methoden getYear() und getMonth() sind seit einigen Jahren in Java "deprecated", d.h. sie könnten in zukünftigen Java Versionen entfallen. Aber da dies in den letzten 7 Jahren nicht passiert ist, können wir damit noch arbeiten und optimistisch sein. Falls die Methoden wirklich entfernt werden, muss man eigene statische Methoden mit dem in Java eingebauten Calender-Objekt erstellen, Codebeispiele dazu gibt es viele im WWW.
</blockquote>

wenn man Text "Erzeugungsdatum" und das Datum in einem Feld haben will geht so: 
"Erzeugungsdatum:"+new SimpleDateFormat("dd.MM.YYYY", Locale.GERMAN).format(new java.util.Date())


==== Zeichenketten zum Datumstyp konvertieren ====

Wenn Sie ein Datum als String-Feld geliefert bekommen, können Sie es mit Groovy zum Typen "java.util.Date" konvertieren, z.B. um danach zu sortieren. Wenn z.B. das Feld „Beginn“ den Typ String hat und gefüllt ist mit dem Wert "18.11.2020 18:05:00", dann können Sie eine Variable vom Typ java.util.Date erzeugen, mit der Expression:

Date.parse("dd.MM.yyyy hh:mm:ss", $F{Beginn})


=== Besonderheiten / Workarounds ===

* Bei Feldern mit Länge 1 klappte einfaches equals nicht, mit einer substring Anweisung geht es dann:

$F{legende_Art des Berichts_value}.substring(0,1).equals("B")

* Folgejahr berechnen: Selbst es das Feld Jahr gibt und es als Integer definiert ist in der Felderinfo, klappt der Bericht nur in JasperReports nicht in SuperX nicht wenn man schreibt: 
$F{legende_Jahr_value}.intValue()+1 
geht nicht, statt dessen: 
new Integer($F{legende_Jahr_value}).intValue()+1
* Statt das Element table zu nutzen kann man auch manuell eine Tabelle erzeugen, in dem man per Rechtsklick auf ein Element Padding und Borders bearbeitet. Siehe http://www.youtube.com/watch?v=LbU6qTj3zQM
* Achten muss man dann darauf, dass Felder die Null sein können nicht „remove when blank“ haben und als TextFieldExpression besser nehmen: $F{Betrag}==null?" ":$F{Betrag}
* außerdem, wenn die erste Spalte einen stretch with overflow hat auch bei „stretch type“ „relative to tallest object“ einstellen
* Zeilenumbruch in Feld 
Markup auf html setzen und dann z.B. "Plan'''''' ''''''"+$F{legende_Jahr_value}


=== Häufig benötigte Transformationen ===


==== Umrechnung Semester-tid in Namen ====

$V{Semester (Schlüssel)}.toString().endsWith("1")?("SS "+$V{Semester (Schlüssel)}.toString().substring(0,4)):("WS "+$V{Semester (Schlüssel)}.toString().substring(0,4)+"/"+(new Integer($V{Semester (Schlüssel)}.toString().substring(0,4))+1).toString())


==== Umrechnung Semester in akad. Jahr ====

Die folgende Formel formt die Semesterzahl aus dem Studierenden-Datenblatt in ein akad. Jahr um nach der Formel "Akad. Jahr=WS + darauf folgendes SS", z.B. WS 2009/2010 und SS 2010 werden zum akad. Jahr 2009:

$F{Semester der Belegung (Schlüssel)}.toString().endsWith("2") ? $F{Semester der Belegung (Schlüssel)}.toString().substring(0,4):(new Integer($F{Semester der Belegung (Schlüssel)}.toString().substring(0,4))-1).toString()

Die Formel nimmt beim WS die ersten vier Stellen des Semester-Schlüssels, und beim SS werden die ersten vier Stellen als Ganzzahl codiert, und dann wird 1 subtrahiert.

Da es diverse Definitionen von Akad. Jahr / Studienjahr / Prüfungsjahr gibt, kann man das obige Beispiel leicht für eigene Bedürfnisse abwandeln.


== Pattern Expression ==

Die Formatierung der Werte kann mit Hilfe des Attributes "Pattern" gesetzt

werden. Hat man allerdings unterschiedliche Werte z.B. Datumsangaben und Währungseinheiten

oder Ganzzahlen und Kommazahlen und möchte diese unterschiedlich formatieren, so kann dies

mit dem Attribut "Pattern Expression" dargestellt werden.

Hier ein Beispiel für die Ausgabe von Ganzahlen und Kommazahlen:

$V{valueMeasure}.doubleValue() == Math.floor($V{valueMeasure}.doubleValue()) &&

!Double.isInfinite($V{valueMeasure}.doubleValue()) ?

"#0;#0" : "###0.00;###0,00"

Hier der Pattern Expression Editor:

[[Datei:JasperReports-Handbuch_ireport_pattern_expression_editor.png]]

Hier das Ergebnis:

[[Datei:JasperReports-Handbuch_ireport_pattern_expression_ergebnis.png]]


== Fortgeschrittene Techniken bei Feldern ==

Textfelder enthalten standardmäßig nur den Feldnamen, aber die zugrunde liegenden [[#2.9.Expression Editor|outline|Ausdrücke]] lassen sich erweitern. Dabei kann auch alle Java Klassen zugegriffen werden, die sich im CLASSPATH befinden, z.B. [[#2.9.2.Umgang mit Zeichenketten|outline|java.lang.String]].

Hier ist ein Beispiel, in dem die Klasse "StringBuilder" (wird mit Java ausgeliefert , java.lang.StringBuilder) genutzt wird, um einen Text auszugeben:

[[Datei:JasperReports-Handbuch_expression_stringbuilder.png]]

Im Ergebnis sieht das so aus:

[[Datei:JasperReports-Handbuch_expression_stringbuilder1.png]]

Das Beispiel verdeutlicht: Man könnte da auch de.meineKlasse.erzeugeText("mein Text") schreiben, und diese Klasse dann in den CLASSPATH bei Jasper Start legen, und voila! Durch diese Funktionalität lassen sich also beliebige Java Klassen einbinden. Das gleiche geht übrigens auch mit Groovy.


== Einrücken von Feldern ==

Das Einrücken von Feldern macht man am besten, in dem man mehrere Textfelder definiert und jeweils eine printWhenExpression auf die Ebene einbaut.

Alternativer Versuch war folgendes:

Wobei Nachteil bei sehr langen Texten, bei denen strech with overflows zur Geltung kommt, dann die zweite Zeile nicht eingerückt wird.

Das Einrücken von Felder kann man für Textfelder (Strings) machen, indem der SuperX-Bericht eine Spalte einruecken definiert, der je nach gewünschter Einrückung eine Anzahl von x enthält, also z.B.

{| class="wikitable"
|-
!
!
!
|-
| Name
| Betrag
| Einrücken
|-
| 1. Überschrift
| 30000
| X (mindestens 1 x nötig)
|-
| 1.1 Unterüberschrift
| 15000
| Xxxxx
|-
| 1.3. UnterUnterübersichrift
| 3000
| xxxxxxxxx
|}

Dann kann man ein Textfeld erzeugen und bei TextFieldExpression einfach eintragen:

$F{Einruecken}.replace('x',' ')+$F{Name}

Für Zahlfelder (z.B. Double) geht das so nicht so gut, weil dann das Pattern der Darstellung ###0,00 nicht mehr greift.

Man definiert drei Felder nebeneinander, Beispiel:

{| class="wikitable"
|-
!
!
!
|-
| $F{Name}
| ${Betrag}

PrintWhenExpression

$F{Hierarchie_Ebene}.intValue()>=6

| ${Betrag}

PrintWhenExpression

$F{Hierarchie_Ebene}.intValue()<6

|}

Bei Ebene 1-5 wird ganz rechts ausgegeben, bei Ebene >=6 wird mittig ausgegeben.


== Berechnungen ==

Bei Berechnungen muss immer auch auf (ich nenne es mal) die Gültigkeit der Variable geachtet werden. Wenn eine Variable eine Summe bildet kann diese für z.B. „jetzt“ oder für eine Gruppe oder den ganzen Report gelten. Je nach Gültigkeit gilt z.B. die Summe nur für die aktuelle Gruppe (bei Gruppenbändern).

Achtung: Es gibt nicht nur eine Gültigkeit bei der Variable selber (Reset type) sondern auch bei dem Element in dem Bericht. Wenn eine Variable in den Bericht gezogen wird, besitzt das entstandene Element eigene Eigenschaften, bei dem dann die „Evulation Time“ eingestellt werden kann.


=== Prozentrechnung ===

Für die Prozentrechnung musst zuerst eine Variable z.B. mit dem Namen "Gesamt" anlegen mit den Eigenschaften:

Calculation = Sum

Reset type = Report

Dannach kann ein Textfeld mit dem Inhalt:

$F{Summe} / $V{Gesamt}

erstellt werden mit den Eigenschaften:

Expression Class = Double

Pattern = #.##0.00 % (kannst du unter Prozent auswählen)

Evaluation Time = Auto

In der Variable „Gesamt“ wird die Summe aus allen Werten des Feldes Summe gezogen.

Bei Prozentberechnungen in Grafiken muss in manchen Fällen der Wert auf 0 überprüft werden. Das kann man z.B. mit folgendem Code machen:

( $V{zahl1} == 0 || $V{zahl2} == 0 ? 0 : ( $V{zahl1} / $V{zahl1} * 100) )

Damit ist dann sichergestellt, dass es keine Probleme bei der Berechnung gibt, auch wenn die Zahlen mal leer sind.


=== Rundung ===

Wenn man runden möchte den Datentyp am besten auf BigDecimal stellen. Ansonsten wird schon mal aus 2,45 gerundet 2,4.


== Hyperlinks ==


=== Externe Links ===

Ein Textfeld kann auch als Hyperlink befüllt und ausgegeben werden. Vorab bemerkt: Hyperlinks funktionieren in internen Viewer von JasperSoft Studio sowie beim Export nach Excel nicht bzw. nur eingeschränkt, zumindestens wenn man POI als Excel Engine nutzt. Selbst wenn Hyperlinks ausgegeben werden, ist in den Sicherheitseinstellungen von Excel oder OpenOffice eine Änderung vorzunehmen, damit Hyperlinks auch aktiv sind. Da es hier komplexte Unterschiede bei MS Excel-/OpenOffice-Versionen gibt, haben wir das Thema nicht weiter verfolgt und raten davon ab.

In den anderen üblichen Ausgabeformaten (PDF, HTML) funktionieren die Hyperlinks.

Dabei gibt es zwei Varianten:

Das Textfeld hat als Markup Typ den Wert "html", und die Hyperlinks werden in HTML-Notation eingefügt. Beispiel:

[[Datei:JasperReports-Handbuch_hyperlink_pfd3.png]]

Hier der Quellcode der textField-Expression zum Kopieren:

$V{Gross_Forsch_Proj_Sprech}.replaceAll( "\n"," " )+"<a href=\"http://www.meinserver.de/url/\">Siehe Details</a>"

Im Ergebnis sieht das dann so aus:

[[Datei:JasperReports-Handbuch_hyperlink_pfd2.png]]

Bei Variante 2 erhält ein ReportElement im Quellcode die entsprechende Eigenschaft. In der von uns genutzten Version von JasperSoft Studio (6.5.1 final) war das noch nicht im GUI bearbeitbar, daher kann man das nur im Quelltext machen. Immerhin "zerstört" JasperSoft Studio dies beim Speichern nicht.

Die Eigenschaft des textField heißt hyperlinkType="Reference" und wird wie folgt belegt:

<textField pattern="" isBlankWhenNull="true" '''hyperlinkType="Reference"'''>

<reportElement mode="Opaque" x="363" y="22" width="259" height="22" forecolor="#000000" backcolor="#FFFFFF" uuid="48c8e2df-f231-4433-8836-309668e0a859">

<printWhenExpression><![CDATA[$V{Gross_Forsch_Proj_Sprech}.length() >100]]></printWhenExpression>

</reportElement>

<box>

<pen lineWidth="0.5"/>

<topPen lineWidth="0.5"/>

<leftPen lineWidth="0.5"/>

<bottomPen lineWidth="0.5"/>

<rightPen lineWidth="0.5"/>

</box>

<textElement textAlignment="Left" verticalAlignment="Middle" rotation="None" markup="html">



<paragraph lineSpacing="Single"/>

</textElement>

<textFieldExpression><![CDATA["Siehe Details"]]></textFieldExpression>

'''<hyperlinkReferenceExpression><![CDATA["http://meinserver/url"]]></hyperlinkReferenceExpression>'''

</textField>

Am Ende des textField wird dann im Element hyperlinkReferenceExpression das Ziel des Hyperlinks definiert. Da dies eine Expression ist, kann man die Hyperlinks auch dynamisch aufbauen. In der Ausgabe dies das dann so aus:

[[Datei:JasperReports-Handbuch_hyperlink_pdf.png]]

Je nach PDF Viewer muss man auch hier in den Sicherheitseinstellungen Hyperlinks aktivieren.


=== Interne Links/Anker ===

Auf einem Text Field kann ein Link eingetragen werden. Dafür muss man einfach mit der rechten Maustaste auf das Textfeld klicken und dann auf Hyperlink klicken.

Das erste Feld oben „Anchor Name Expression“ kann einen Text enthalten, auf den von einer anderen Stelle verwiesen werden kann. Es ist also eine Markierung.

Wenn ich einen Hyperlink Type wähle, kann ich auch Verweise in den generierten Bericht erzeugen. Z.B. kann ich hier den Type „LocalAnchor“ wählen.

Um z.B. ein Inhaltsverzeichnis zu erzeigen, welches im PDF bei klick auf ein Element dort hin springen soll, gehe ich zunächst zu der Stelle an der die Sprungmarke gesetzt werden soll und erzeuge dort ein Text Field mit der „Anchor Name Expression“ z.B. „Überschrift1“. Das Inhaltsverzeichnis muss dann auch aus Text Fields erzeugt werden und dort wähle ich dann bei Hyperlink type „LocalAnchor“. Nun habe ich unter der Auswahl von dem Hyperlink type ein neues Eingabefeld „Hyperlink Anchor Expression“. Dort trage ich jetzt exakt den gleichen Text „Überschrift1“ ein und im generierten PDF kann ich dort drauf klicken um an die Markierte Stelle zu kommen.


== Berichts-Properties setzen ==

Es gibt auf Berichtsebene die Möglichkeit, die Ausgabe der Berichte über sog. "Properties" zu steuern, teilweise auch formatspezifisch. So können Sie z.B. steuern, daß bei der Ausgabe nach Excel Zahlenfelder als Zahlenfelder ausgegeben werden, nicht als Textfelder.

Um die Berichts-Properties zu setzen, können Sie dies entweder für einzelne Berichte, order auch Server-weit einstellen.

Bei einzelnen Berichten gehen Sie im Report Inspector auf das oberste Element, und dort auf "Eigenschaften".

[[Datei:JasperReports-Handbuch_report_properties1.png]]

Sie erhalten dann eine Liste der Eigenschaften:

[[Datei:JasperReports-Handbuch_report_properties2.png]]

Dort können Sie Zeilen hinzufügen, bearbeiten und löschen. Eine Erläuterung der jew. Property erhalten Sie in dem jew. Dialog.

Um eine Property systemweit zu speichern, legen Sie eine Textdatei mit dem Namen "jasperreports.properties" an, und legen diese in den CLASSPATH. Im Kontext von Tomcat ist dies das Verzeichnis webapps/superx/WEB-INF/classes.


== Seitenlayout ==


=== Seitenumbrüche ===

Es gibt drei Typen von Seitenumbrüchen:

* Wenn der gesamte Bericht paginiert ist (Report-Eigenschaft "Ignore Pagination"="false"), berechnet JR aufgrund des Seitenformats die Seitenumbrüche automatisch, und fügt auch, sofern vorhanden, die Bänder "page header" und "page footer" hinzu.
* Bei eingeschalteten Eigenschaften des jew. Bandes "Start on a new page=true" werden Seitenumbrüche ebenfalls aufgeführt
* Es gibt für manuelle Seitenumbrüche in der Palette das Element "Break", das an beliebiger Stelle einen manuellen Seitenumbruch einfügt. Nun ist die Frage: wenn gesamte Bericht nicht paginiert ist ("Ignore Pagination"="true"), was dann bei einem Break passieren soll. In älteren JR Versionen (vor 4.8) wurde der Break trotzdem gesetzt. In Versionen ab 4.8 passiert das nicht mehr, man kann aber ab Version 5.1 über die Berichts-Property 
net.sf.jasperreports.page.break.no.pagination=apply 
das alte Verhalten nachbilden.

In JasperSoft Studio oder iReport kann man zusätzlich noch beim Rendern des Berichts über den Parameter JRParameter.IS_IGNORE_PAGINATION steuern, ob Seitenumbrüche ausgeführt werden. Dies überlagert die Berichtseinstellung, wenn es angehakt ist. Das ist z.B. sinnvoll, wenn Sie im PDF Export Seitenumbrüche haben wollen, in Excel oder HTML aber nicht.

Leider kann man diesen Parameter nicht im Servlet setzen. Wenn Sie Seitenkopf/Fuß bei PDF wünschen, bei Excel aber nicht, nutzen Sie die Anleitung [[#2.21.5.Seitenkopf und Seitenfuß bei Excel unterdrücken|outline|unten]].

Es gibt verschiedene Möglichkeiten, wie sich das Detailband bei einem Seitenumbruch verhalten soll. Diese werden über den ‚Split Type‘ des Bandes gesteuert. Beispiel:

Bei einem Seitenumbruch wird die aktuelle Zeile des Detailbandes aufgeteilt und geht auf der nächsten Seite weiter. Der ‚Split Type‘ steht auf Stretch.

[[Datei:JasperReports-Handbuch_Eingebettet_011.png|642x170px]]

Falls erwünscht ist, dass jede Zeile ganz dargestellt wird, kann der ‚Split Type‘ auf Prevent gestellt werden:

[[Datei:JasperReports-Handbuch_Eingebettet_012.png|300x281px]]Das Ergebnis sieht wie folgt aus:

[[Datei:JasperReports-Handbuch_Eingebettet_013.png|642x223px]]


=== Die Höhe von Textfeldern dynamisch anpassen ===

[[Datei:JasperReports-Handbuch_layout1.png]]

Textfelder besitzen die Eigenschaft „Stretch With Overflow“. Wird diese aktiviert, passt das Textfeld dynamisch seine Größe, falls der Inhalt nicht in das Feld passt. Der Text bricht um und die Höhe des Feldes wird vergrößert. Damit auch alle anderen Felder derselben Zeile ihre Größe entsprechend anpassen wird der „Stretch Type“ aller Felder dieser Zeile auf „Relative To Tallest Object (deprecated)“ gesetzt. Die Felder passen ihre Höhe dann dem höchsten Feld dieser Zeile an. Im Detailband genügt dies. Für Bänder mit festgelegter Zeilenanzahl, wie beispielsweise dem Titelband ist eine weitere Einstellung vorzunehmen.

Um im Titelband die Funktion „Stretch With Overflow“ nutzen zu können, ist es notwendig allen Feldern in darunterliegenden Zeilen den „Position Type“ „Float“ zuzuweisen. Die Position der Felder verändedrt sich dann entsprechend der Höhe darüberliegender Felder.

[[Datei:JasperReports-Handbuch_layout2.png]]


=== Bericht ausgeben, ohne Dateninput ===

Wenn der Bericht bzw. das Layout mit Titelband etc. ausgegeben werden soll, obwohl es keine Daten gibt, dann wird die Funktion ‚When No Data Type‘ auf ‚All Sections No Detail‘ gestellt.

[[Datei:JasperReports-Handbuch_Eingebettet_014.png|336x374px]]


== Besonderheiten beim Export nach Excel ==

Für jedes Exportformat gibt es auf Berichtsebene bzw. darunter spezielle Properties, die Feinheiten des Zielformates festlegen. Dies wird im folgenden anhand des Excel-Exports von Formeln und Namen von Arbeitsblättern (Sheet-Names) gezeigt.

Bitte beachten Sie dass diese Hinweise für den "alten" Excel Export ("xls") gelten. Für die Exportformate xlsx, JExcel-API oder OpenOffice-Spreadsheets funktionieren diese teilweise nicht.

Um leere Zeilen im Excelexport zu vermeiden, im jrxml-Kopf:

<property name="net.sf.jasperreports.export.xls.collapse.row.span" value="true"/>

<property name="net.sf.jasperreports.export.xls.remove.empty.space.between.columns" value="true"/>

<property name="net.sf.jasperreports.export.xls.remove.empty.space.between.rows" value="true"/>

wenn man Zahlenanpassung möchte

<property name="net.sf.jasperreports.export.xls.auto.fit.row" value="true"/>

<property name="net.sf.jasperreports.export.xls.font.size.fix.enabled" value="true"/>

→ font wird ggfs. verkleinert

<property name="net.sf.jasperreports.print.keep.full.text" value="true"/>


=== Excel-Formeln ===

Es gibt auch die Möglichkeit Zahlen nicht nur vorab zu berechnen, sondern beim Export nach Excel als Excel-Formel zu übergeben.

Um diese Funktion zu aktivieren muss im JRXML die Property mit folgender Zeile eingefügt werden:

<property name="net.sf.jasperreports.export.xls.detect.cell.type" value="true"/>

Oder über die Report Properties:

[[Datei:JasperReports-Handbuch_excel_export_detect_cell_type1.png]]

Danach können in jedem Text Field in der Property expression:

[[Datei:JasperReports-Handbuch_excel_export_detect_cell_type2.png]]

folgende Einträge ergänzt werden:

[[Datei:JasperReports-Handbuch_excel_export_detect_cell_type3.png]]

Rechts neben net.sf.jasperreports.export.xls.formula wird die Formel für Excel eingetragen, allerdings ohne = am Anfang. Außerdem werden nicht alle Excel-Formeln unterstützt, insbesondere nicht deren deutsche Lokalisierung (z.B. oben SUMME(D119...). Details finden Sie in der [https://poi.apache.org/spreadsheet/formula.html POI]-Dokumentation. Um zu erfahren wie die Felder lauten, welche berechnet werden sollen, am besten den Bericht einmal ausführen und in Excel anzeigen lassen. Achtung: Wenn der Bericht noch bearbeitet wird, können sich die Felder noch verändern.

Bei net.sf.jasperreports.export.xls.pattern können speziell für Excel Formatangaben gemacht werden. In dem obigen Beispiel "#,##0.00;-#,##0.00" gibt es 2 Nachkommastellen und ein Tausender-Trennzeichen. Wenn z.B. Tausende von Euro angezeigt werden sollen, nimmt man als Pattern #.

<blockquote>Fallstrick: in der von uns getesteten Version (4.1.3) wurde die Property net.sf.jasperreports.export.xls.formula nur dann ausgewertet, wenn das das jew. Textfeld eine korrekte "Text field expression" hat, sie darf also nicht leer sein. Ob das ein Bug ist oder nicht ist uns derzeit unklar.
</blockquote>
Beispiel für eine komplexe Summenformel SUM(D7:D20,D28,D33,D40)

Man kann die Formel auch als Expression formulieren, z.b. um eine Division durch 0 zu verhindern. Setzen Sie dazu das Häkchen bei "Use an expression":

[[Datei:JasperReports-Handbuch_excelformula_expression.png]]

Das obige Beispiel führt die Formel "D91/D149" nur aus, wenn die Variable $V{Haush_Professoren_1} (die Quelle für die Zelle D149) einen Wert größer 0 hat. Wenn nicht, wird keine Formel reingeschrieben, sondern der Wert 0.

Diese Funktion bietet natürlich noch viel mehr Möglichkeiten, z.B. könnte man damit Excel-Zellennummern dynamisch berechnen etc. Beispiele dazu finden Sie in den JasperReport Demos in demo/samples/xlsformula/reports/XlsFormulaReport.jrxml.


==== Zeilennummern dynamisch berechnen (Ein Beispiel) ====

Will man dass in der gesamten Exceldatei immer Spalte F=D+E ist, braucht man nicht für jede Zeile feste Formeln eintragen.

Als Erstes schaut man in welcher Zeile die eigentlichen Daten anfangen, also z.B. nach den zwei Headerzeilen ganz am Anfang der Tabelle und den 3 Spaltenüberschriften, die pro Seite wiederholt werden.

Hier ein Beispiel

($F{Zweckbestimmung}.isEmpty()||($F{Soll}==null&&$F{Reste}==null))?"":"SUM(D"+(($V{PAGE_NUMBER}.intValue()*3)+$V{REPORT_COUNT}.intValue()+2)+",E"+(($V{PAGE_NUMBER}.intValue()*3)+$V{REPORT_COUNT}.intValue()+2)+")"

Elegant geht es auch so

($F{Zweckbestimmung}.isEmpty()||($F{Soll}==null&&$F{Reste}==null))?"":"INDIRECT(\"D\" & ROW())+INDIRECT(\"E\" & ROW())"

Das hat nur den Nachteil, dass die Formel in Excel nicht so schön ist.


==== WENN-/IF-Formel – '''Ein''' Fallstrick ====

Ein Fallstrick, der uns einige Stunden Arbeitzeit gekostet hat: die IF-Formel wird in OpenOffice und MS Excel mit dem Trennzeichen ";" für die THEN- und ELSE-Bedingung formuliert. JasperReports nutzt als Trennzeichen aber ",". Interessanterweise wird dann im fertigen Excel das "," als ";" angezeigt.


==== SUMIF – Summen mit Bedingungen (Bsp.: Zwischensummen ignorieren) ====

Wenn die Summe über einen großen Bereich gezogen werden soll, in dem auch Zwischensummen vorkommen, gibt es die Folgende Formel:

SUMIF(A"+$V{zeile_start}.intValue()+":A"+$V{zeile_ende}.intValue()+",\"<>Summe*\",B"+$V{zeile_start}.intValue()+":B"+$V{zeile_ende}.intValue()+")

Wenn die Zwischensummen mit addiert werden würden, wäre das Ergebnis doppelt so hoch wie es sein sollte. Die Funktion SUMIF beinhaltet 3 Bereiche. Zuerst wird der Bereich eingegeben, auf den die Bedingung angewendet wird:

A"+$V{zeile_start}.intValue()+":A"+$V{zeile_ende}.intValue()+"

Hier ist das z.B. von A1 bis A10.

Danach kommt die Bedingung:

\"<>Summe*\"

Das bedeutet, es werden alle Zeilen genommen, die '''''NICHT''''' mit „Summe“ anfangen.

Als letztes kommt der Bereich, der summiert werden soll:

B"+$V{zeile_start}.intValue()+":B"+$V{zeile_ende}.intValue()+"

Hier ist das z.B. von B1 bis B10.

In diesem Beispiel werden alle Zahlen zwischen B1 und B10 aufsummiert, wenn in der entsprechenden Zeile in der Spalte A der Text nicht mit „Summe“ beginnt.


==== Statt 0-Werten eine leere Zelle ausgeben ====

Im Standardfall wird eine 0 ausgegeben, falls eine Formel in Excel auf leere Zellen oder Zellen mit einer 0 verweist. Um stattdessen eine leere Zelle auszugeben wird die Property Property net.sf.jasperreports.export.xls.pattern genutzt. Das obige Beispiel wird erweitert:

###0.00;-###0.00;;@

Die jeweiligen Zellen weisen nun 2 Nachkommastellen aus und zudem werden 0-Werte nicht mehr angezeigt.


==== OpenOffice vs Excel ====

OpenOffice kommt mit folgender Berechnung klar

"INDIRECT(\"E\" & ROW())+INDIRECT(\"F\" & ROW())-INDIRECT(\"G\" & ROW())-INDIRECT(\"H\" & ROW())":""

Excel macht hier Ärger, wenn eine der Zellen Null ist, wird als Gesamtergebnis #WERT angezeigt, entweder Sum-Formel benutzen, oder noch mal mit IF prüfen, ob Zelle gefüllt ist

Struktur ist (IF(Zelle leer,0,sonst Zellenwert))

"IF(INDIRECT(\"E\" & ROW())=\"\",0,INDIRECT(\"E\" & ROW()))+IF(INDIRECT(\"F\" & ROW())=\"\",0,INDIRECT(\"F\" & ROW()))-IF(INDIRECT(\"G\" & ROW())=\"\",0,INDIRECT(\"G\" & ROW()))-IF(INDIRECT(\"H\" & ROW())=\"\",0,INDIRECT(\"H\" & ROW()))":""


=== ‚Stretch with Overflow‘ in Excel korrekt verarbeiten ===

Wenn Sie eine Zelle haben mit besonders langem Text, z.B. „Unterstützungen auf Grund der Unterstützungsgrundsätze, Fürsorgemaßnahmen sowie Kosten nach dem Arbeitssicherheitsgesetz“, hilft es, nur bei der Zelle, Line Spacing auf double zu setzen, dann sieht es in Excel besser aus.

Es wird das Stretch richtig verarbeitet.

<property name="net.sf.jasperreports.export.xls.auto.fit.row" value="true"/>

<property name="net.sf.jasperreports.export.xls.font.size.fix.enabled" value="true"/>

→ verkleinert fonts bei bedarf

<property name="net.sf.jasperreports.print.keep.full.text" value="true"/>


=== Pagination in Excel-Dokumenten ===

In Excel-Dokumenten in die Seitengröße naturgemäß irrelevant. Trotzdem wird das im jrxml gesetzte Seitenformat beim Excel-Export beachtet. Das stellt sich so dar, dass im Excel-Dokument der „Rest der Seite“ durch einzelne breitere beziehungsweise höhere Zellen gefüllt wird. Das sieht beispielsweise folgendermaßen aus:

[[Datei:JasperReports-Handbuch_excel_export_pagination1.png]]

Unter dem Tabellenschluss ist die Zeile 84 so hoch, dass die im jrxml eingestellte Seitenhöhe erreicht ist. Um das zu verhindern wird für den gesamten Bericht isIgnorePagination=“true“ gesetzt. Die Einstellung wird im source-Code ganz oben im Tag <jasperReport isIgnorePagination=“true“> gesetzt oder über die grafische Oberfläche:

[[Datei:JasperReports-Handbuch_excel_export_pagination2.png]]


=== Excel-Export in einzelne Tabellenblätter ===

Normalerweise werden beim Export nach Excel die Berichtsinhalte in das erste Tabellenblatt geschrieben. Je nachdem wie Sie auf Berichtsebene die Property net.sf.jasperreports.export.xls.one.page.per.sheet setzen, wird der Seitenumbruch gesteuert. Setzen Sie den Wert auf "true", dann führt jeder Seitenumbruch zu einem neuen Sheet bzw. Arbeitsblatt in der Excel-Datei. Standardmäßig werden diese dann "Page 1", Page 2" etc. benannt.

Wenn Sie die Namen der Sheets explizit vergeben wollen, können Sie dies wie folgt machen: Wenn Sie z.B. die Berichtsproperty net.sf.jasperreports.export.xls.sheet.names.all auf den Wert

"Hauptseite/wichtige Seite/Unwichtige Seite" setzen, bekommen Sie drei Sheets mit den jew. Namen, d.h. der "/" fungiert als Trennzeichen. Dementsprechend sollte im Namen des Sheets kein "/" auftauchen.

Seit JR 4.1 gibt es auch die Möglichkeit, die Sheetnamen dynamisch zu vergeben. Auch hier werden Properties mit Expressions genutzt.

Es gibt verschiedene Möglichkeiten Berichtsinhalte in verschiedene Excel-Tabellenblätter zu verteilen. Im Folgenden werden zunächst Möglichkeiten betrachtet, welche bei Einzelberichten in Frage kommen. Danach geht es um die klassische Haupt- und Unterberichtsstruktur und zuletzt um Booklets, welche die in den meisten Fällen wohl elegantere Alternative zu klassichen Haupt- und Unterberichten darstellen.


==== Einzelne Berichte ====

Nehmen wir an wir haben einen Bericht mit der Gruppierung auf die Spalte "LFB", im Gruppenkopf befindet sich ein Text Field mit der Expression $F{LFB}.

Sie können diesem Textfeld eine Property net.sf.jasperreports.export.xls.sheet.name geben:

[[Datei:JasperReports-Handbuch_excel_export_sheets_names.png]]

Das Textfeld erhält somit beim Füllen des Berichts den jew. Wert, z.B. "Anglistik, Amerikanistik", und diese Überschrift steht auch im Gruppenkopf. Wenn der Gruppenkopf das Attribut "Start on a new page" hat, dann beginnt der Gruppenkopf auf einer neuen Seite und, dank der Berichts-Property net.sf.jasperreports.export.xls.one.page.per.sheet , erzeugt Excel / OpenOffice dann ein neues Sheet mit dem Namen Anglistik, Amerikanistik. Beim Sheetnamen soll nur sichergestellt werden, dass kein "/" im Text vorkommt, daher der replace-Befehl zur Sicherheit. Hier ein Screenshot in OpenOffice:

[[Datei:JasperReports-Handbuch_excel_export_sheets_names2.png]]

Man kann das gesamte Verhalten auch deaktivieren, indem man auf Berichtsebene das Attribut "Ignore Pagination" auf "true" setzen. In diesem Falle werden alle Seitenumbrüche ignoriert.

<blockquote>Hinweis für SuperX/Edustore Nutzer: leider haben wir in älteren Kernmodul-Versionen dieses Attribut " Ignore Pagination" im Servlet fest auf "true" gesetzt, so dass Sie diese Funktion im Servlet erst ab Version SuperX 4.5 bzw. HISinOne-BI 7.0 nutzen können.
</blockquote>

==== Haupt- und Unterberichte ====

Das vorherige Kapitel hat aufgezeigt, wie innerhalb eines einzelnen Einzelberichtes mit gezieltem setzen von Seitenumbrüchen ein solcher Berichte auf verschiedene Tabellenblätter eines Excel-Dokumentes augeteilt wird.

Um mehrere Einzelberichte in einem Excel-Dokument gesondert auf verschiedene Tabellenblätter aufzuteilen eignen sich klassiche Haupt- und Unterberichtsstrukturen (vgl. Kapitel 3.5). Die simpelste Methode wäre das Seitenlayout eines Berichtes so groß zu wählen, dass der gesamte Bericht auf eine Seite passt.

Falls Haupt- und Unterberichte verwendet werden, darauf achten, dass der Hauptbericht direkt unter dem letzten Unterberichtselement endet. Ansonsten entsteht ein weiteres leeres Tabellenblatt. Der folgende Screenshot zeigt, wie es nicht sein sollte. Hier muss das Summary-Band verkleinert werden, sodass es mit dem Unterberichtselement endet.

[[Datei:JasperReports-Handbuch_excel_export_main-_subreport.png]]


==== '''Individuelle Gestaltung''' bei Booklets ====

Booklets bieten diverse Vorteile beim Gestalten der einzelnen Seiten beziehungsweise Sheets. Denn jeder Unterbericht kann hier individuell formatiert werden. Dies betrifft beispielsweise die Definition von Sheetnamen, da hierfür die Eigenschaft "Tab name expression" im "Buch"-[[#2.8.1.Hauptbericht im Booklet|outline|Bericht]] vorgesehen ist. Auch das Problem, dass ein Sheet in diesem Falle nicht mehrere Seite umfassen darf (und man somit die Seitengröße unrealistisch groß machen muss) ist damit behoben.

Eine Ausnahme stellen jedoch die Properties dar. Diese werden im Hauptbericht gesetzt und gelten für alle Unterberichte.


=== Das Drucklayout in Excel konfigurieren ===


==== '''Seitenränder und Kopfzeile im Drucklayout formatieren''' ====

Zum Anlegen eines Textes in der Kopfzeile gibt es die Properties

<property name="net.sf.jasperreports.export.xls.sheet.header.center">

<property name="net.sf.jasperreports.export.xls.sheet.header.right">

<property name="net.sf.jasperreports.export.xls.sheet.header.left">

Je nach gewünschter Position wird der jeweiligen Property ein Wert übergeben. Ein Beispiel:

<property name="net.sf.jasperreports.export.xls.sheet.header.center">

<![CDATA[&"Liberation Sans,Bold"&10Meldung der Ist-Besetzung]]>

</property>

<property name="net.sf.jasperreports.export.xls.sheet.header.right">

<![CDATA[&"Liberation Sans,Bold"&10Anlage 1 &"Liberation Sans,Regular"&10 (zu VwV HWiF 3.2.1)]]>

</property>

In diesem Beispiel wird zentral der Text „'''Meldung der Ist-Besetzung'''“ übergeben. Der Text ist in der Schriftart Liberation Sans und fettgedruckt formatiert (&"Liberation Sans,Bold"), sowie in Schriftgröße 10 (&10).

Rechts wird der Text „'''Anlage 1 '''(zu VwV HwiF 3.2.1)“ verwandt. Der erste Teile „'''Anlage 1'''“ ist wie der zentrale Text formatiert (&"Liberation Sans,Bold"&10). Für den zweiten Teil „(zu VwV HwiF 3.2.1)“ wird von Fett- auf Regulärdruck gewechselt (&"Liberation Sans,Regular"&10). Weitere Möglichkeiten zur Formatierung finden sich auf https://poi.apache.org/apidocs/dev/org/apache/poi/xssf/usermodel/extensions/XSSFHeaderFooter.html.

Damit die Kopfzeile im Drucklayout sichtbar ist, ist es notwendig den Seitenrand groß genug zu gestalten. Dafür werden folgende Properties genutzt:

<property name="net.sf.jasperreports.export.xls.print.page.left.margin" value="20"/>

<property name="net.sf.jasperreports.export.xls.print.page.right.margin" value="20"/>

<property name="net.sf.jasperreports.export.xls.print.page.top.margin" value="40"/>

<property name="net.sf.jasperreports.export.xls.print.page.bottom.margin" value="10"/>



==== Vordefinierte Zeilen im Drucklayout auf jeder Seite wiederholen ====

Um im Drucklayout beispielsweise einen Tabellenkopf auf jeder Seite zu wiederholen, wird die Property

<property name="net.sf.jasperreports.export.xls.sx_repeating.rows.range" value="3:7"/>

genutzt (dafür eigene Klasse de.superx.servlet.SxJRXlsExporter geschaffen und de.superx.servlet.JasperCreator angepasst – aktuell in NHS-Pack für 7.1 enthalten). Der Wert gibt an, welche Zeilen des Excel-Dokumentes im Drucklayout auf jeder Seite wiederholt werden. Im Beispiel (''value="3:7"'') sind die Zeilen 3 bis 7 betroffen.


==== Seitenumbrüche im Drucklayout verhindern ====

Teilweise ist es wünschenswert Seitenumbrüche im Drucklayout zu verhindern, sowohl in der Breite als auch in der Höhe. Hierfür werden die Properties

<property name="net.sf.jasperreports.export.xls.fit.width" value="1"/>

<property name="net.sf.jasperreports.export.xls.fit.height" value="1"/>

genutzt. Also value kommen hier 1 und 0 für entweder true oder false infrage. Setzt man der Wert true, dann wird nicht umgebrochen. Das bedeutet für dieses Beispiel, dass der gesamte Inhalt des Excel-Dokuments auf eine Seite gedruckt würde.


=== Zellen verbinden ===

<property name="net.sf.jasperreports.export.xls.export.xls.sx_cell_merge" value="0,6,0,7|1,2,3,4"/>

1,1,4,1 - will merge from B2 to E2. Remember it is zero based indexing.


=== Zellschutz aktivieren ===

<property name="net.sf.jasperreports.export.xls.password" value="gmmmyflb"/>

→ Alle Zellen sind mit Passwort geschützt.

Wenn bestimmte Spalten/Zeilen nicht geschützt sein sollen:

Property net.sf.jasperreports.export.xls.cell.locked false.

Dies kann man auch über eine komplexe PropertyExpression steuern, z.B.

(

($F{Zeile}!=null&&(

$F{Zeile}.indexOf("A")>-1||

$F{Zeile}.indexOf("B")>-1||

$F{Zeile}.indexOf("C")>-1||

$F{Zeile}.equals("I.")||

$F{Zeile}.equals("II.")||

$F{Zeile}.equals("III.")||

$F{Zeile}.equals("IV.")||

$F{Zeile}.equals("V.")||

$F{Zeile}.equals("VI.")||

$F{Zeile}.equals("VII.")||

$F{Zeile}.equals("VIII.")))||

($F{Kontengruppe}!=null&&$F{Kontengruppe}.equals("53,54,58"))||

($F{Name}!=null&&(

$F{Name}.startsWith("= Summe der (ordentlichen")||

$F{Name}.startsWith("Ordentliche ")||

$F{Name}.startsWith("- ordentliche")||

$F{Name}.startsWith("+/- Finanz")||

$F{Name}.startsWith("Summe Investitionen")||

$F{Name}.startsWith("Summe Finanzbedarf")||

$F{Name}.startsWith("Summe Deckung")||

$F{Name}.startsWith("5.1 E")||

$F{Name}.startsWith("Summe sonstige betriebl")||

$F{Name}.startsWith("Sonstige betriebliche")||

$F{Name}.startsWith("5.1.) Erträge aus Zuweisungen")||

$F{Name}.startsWith("Materialaufwand")||

$F{Name}.startsWith("= Summe Materialaufwand")||

$F{Name}.startsWith("Personalaufwand")||

$F{Name}.startsWith("= Summe Personalaufwand")||

$F{Name}.startsWith("Sonstige betriebliche Aufwendungen")||

$F{Name}.startsWith("= Summe sonstige betriebliche Aufwendungen")

)

))?"true":"false"


=== Zellen fixieren ===

In Jaspersoft Studio können Sie festlegen, dass beim Excel-Export bestimmte Zeilen und Spalten fixiert werden, indem Sie spezielle Eigenschaften für den Export konfigurieren.

Um Zeilen und Spalten in Excel zu fixieren, müssen Sie die Eigenschaften

''net.sf.jasperreports.export.xls.freeze.row ''

und

''net.sf.jasperreports.export.xls.freeze.column''

konfigurieren.

Wenn Sie möchten, dass die erste Zeile und die erste Spalte fixiert werden:

* ''net.sf.jasperreports.export.xls.freeze.row = 2''
* ''net.sf.jasperreports.export.xls.freeze.column = B''

Nach dem Export werden in Excel die erste Zeile und die erste Spalte fixiert, und der Rest des Arbeitsblatts bleibt scrollbar.

''<property name="net.sf.jasperreports.export.xls.freeze.column" value="B"/>''

<property name="net.sf.jasperreports.export.xls.freeze.row" value="2"/>


=== Hintergrund- oder Textfarben beim Excel-Export ===

Beim Excel Export werden Zellen, die ein Rechteck mit einer Print-When-Expression zugewiesen bekommen haben, u.U. nicht richtig wiedergegeben, während es beim PDF Export klappt. Um dies zu beheben müssen Sie

1. den Farbraum beim Excel Export erweitern: Excel unterstützt bei Hintergrund- oder Vordergrundfarben nur wenige [http://dmcritchie.mvps.org/excel/colors.htm Farbcodes]. Für spezielle Farben nach RGB-Wert muss die Berichts-property

<property name="net.sf.jasperreports.export.xls.create.custom.palette" value="true"/>

gesetzet werden (benötigt Bibliothek org-netbeans-core.jar im Classpath der Anwendung)

2. Statt farbiger Textfelder oder Rechtecke mit "Print-When-Expression" müssen Sie [[#2.11.Conditional styles - Zeilen fett machen|outline|Conditional Styles]] nutzen.

3. Wenn Sie mit Hintergrundfarben arbeiten, müssen die Textfelder und die jew. Styles die Eigenschaft "Opaque"="true" haben.

4. Beim Export nach Excel müssen Sie das JExcelApi nutzen. Dies ist bei SuperX seit Kernmodul 4.5 der Standard, bei HISinOne-BI seit Version 7.1.


=== Seitenkopf und Seitenfuß bei Excel unterdrücken ===

Wenn Ihr Bericht normalerweise ein Band "Page Header" bzw. "Page Footer" hat, können Sie dies beim Exportformat XLS unterdrücken (z.B. wenn Sie dort keine Seitenzahlen wünschen, bei PDF aber schon).

Setzen Sie dazu die Berichts-Property

<property name="net.sf.jasperreports.export.xls.exclude.origin.band.1" value="pageHeader"/>

<property name="net.sf.jasperreports.export.xls.exclude.origin.band.2" value="pageFooter"/>

Beim Ausgabeformat XLSX heißen die Properties:

<property name="net.sf.jasperreports.export.xlsx.exclude.origin.band.1" value="pageHeader"/>

<property name="net.sf.jasperreports.export.xlsx.exclude.origin.band.2" value="pageFooter"/>

Dies klappt ab JR Version 4.5, sie können diese Properties aber lediglich im XML-Quellcode hinzufügen.


== Dimension Tausend-Euro ==

In Excel als Dimension Tausend-Euro ausgeben, mit zwei Nachkommastellen

In Deutschem Excel bei manueller Angabe benutzerdefiniertes Format #.##0,00.

In Jasper muss Amerikanische Vorlage sein:

-> #,##0.00

Bei Excel kann man als Property Expresion net.sf.jasperreports.export.xls.pattern z.B. nehmen

#, → zeigt nur Tausender Werte an

#,##0.00, → zeigt Tausernder Werte, mit zwei Nachkommastellen an

der Werte selber ist einfach $F{Soll}

Bei PDF/HTML muss man den Wert duch 1000 teilen $F{Soll}.doubleValue()/1000

und dann als Pattern z.B. #,##0.00;-#,##0.00

Die Rundung macht das Pattern.


= Nutzung in Edustore =


== Berichtsentwicklung bei Grunddaten und Basisberichten ==


=== Allgemein ===

In den Grunddaten- und Basisberichten kann man beliebige Ergebnistabellen lokal als XML speichern, und dann als Datenquelle in JasperReports einbinden. Dann kann man den Bericht lokal gestalten, und, wenn er fertig ist, in die Weboberfläche einhängen. Die XML Datei wird nur für die Testausgabe bei JasperReports verwendet und dient als Ersatz der Datenbank. Wenn der Bericht in der Weboberfläche eingehängt ist, wird dieser direkt mit frischen Daten versorgt.

Für die Folgenden 2 Punkte „Datenquelle erzeugen“ und „Template erzeugen“ gibt es [http://www.superx-projekt.de/doku/benutzerhandbuch/movies/jasper_erzeugen.viewlet/jasper_erzeugen_viewlet_swf.html hier] einen Kurzfilm.

[[Datei:JasperReports-Handbuch_vergleich_jrxml_xml_zusammen.png]]


=== Datenquelle erzeugen ===

Wenn die Ergebnistabelle eines Berichtes vorliegt, erhält man über den XML Export von SuperX die Datenquelle für den Jasper Report.

[[Datei:JasperReports-Handbuch_iReport-Datasource_erstellen.jpg]]

Diese Datei speichert man lokal ab: Wenn das Ergebnis im Browser geöffnet wurde muss man sich den Quelltext der Seite anzeigen lassen, den Quelltext komplett markieren und kopieren ( Tastenkombination Strg + a und dann Strg + c), in einen UTF-8-fähigen Texteditor einfügen (Strg + v) und dann als eine xml-Datei abspeichern.

Falls der Tomcat in ISO Kodierung läuft, muss für JasperReports in der ersten Zeile bei encoding ein UTF-8 eingetragen werden.

Beispiel:

<?xml version="1.0" encoding="ISO-8859-1"?>

wird ersetzt mit:

<?xml version="1.0" encoding="UTF-8"?>

In JasperReports sind dann folgende Schritte zu tun, um die neue Datenquelle einzubinden.


==== Datenquelle in JasperSoft Studio ====

Die Datenquellen heißen hier "Data Adapters" und werden im Repository hinzugefügt:

[[Datei:JasperReports-Handbuch_jaspersoft_datasource1.png]]

<blockquote>Achtung: wenn Sie JasperSoft in Ihrem vorhandenen Eclipse als Plugin installiert haben, sehen Sie den Reiter "Repository" nicht; in diesem Fall liegen die Data Adapter im jew. Projekt.
</blockquote>
Im Assistenten geben Sie XML-Document als Datentyp an, und im nächsten Reiter spezifizieren Sie das Format:

[[Datei:JasperReports-Handbuch_jaspersoft_datasource2.png]]

Das Datumsformat ist bei Edustore das deutsche Schema "dd.MM.yyyy", und das Zahlenformat ist eine Zahl mit 6 Nachkommastellen und "." als Dezimaltrenner, also "#0.######". Bei Locale müssen Sie "Englisch" angeben, weil Dezimalzahlen in den Edustore-XML-Quellen den "." als Dezimaltrenner haben.

Wichtig ist auch das Ankreuzfeld "Use the report Xpath expression", dies müssen Sie immer ankreuzen.


==== Datenquelle in iReport ====

Klick auf „Report Datasources“. Es öffnet sich ein Fenster, in dem die vorhandenen Datenquellen angezeigt werden.

[[Datei:JasperReports-Handbuch_iReport-Datasource_1.jpg]]

In diesem Fenster Klickt man auf „New“ um eine neue Datenquelle anzulegen.

[[Datei:JasperReports-Handbuch_iReport-Datasource_2.jpg]]

Nun wählt man „XML file datasource“ aus und klickt auf „Weiter“.

[[Datei:JasperReports-Handbuch_iReport-Datasource_3.jpg]]

Im letzten Schritt wählt man einen Eindeutigen Namen aus, der auch später in dem Dropdown Menü erscheint, gibt den Dateipfad an und ändert die restlichen Einstellungen wie im Screenshot.

[[Datei:JasperReports-Handbuch_iReport-Datasource_4.jpg]]

Die Formate für Datum und Nummer müssen angegeben werden, da sonst die amerikanischen angenommen werden. Bei Locale müssen Sie "Englisch" angeben, weil Dezimalzahlen in den Edustore-XML-Quellen den "." als Dezimaltrenner haben.

<blockquote>Hinweis: in JasperReports 3.7.1 werden trotz des korrekten Zahlenformats die Dezimalstellen von Beträgen immer mit ",00" wiedergegeben. Dies liegt an der "Locale", man muss diese auf "Englisch" umstellen. Das Problem ist allerdings: sobald man das macht, kann man die XML-Datenquelle in der Datenquellenverwaltung nicht mehr ändern, d.h. man muss sie bei Änderungen löschen und neu einfügen.
</blockquote>
Nach dem Speichern erscheint die Datenquelle im dropdown Menü und kann ausgewählt werden. Damit man die Datenquelle nutzen kann, braucht man auch noch ein Template.


=== Template erzeugen ===

Um ein leeres Template zu erzeugen, geht man wieder in die Ergebnistabelle der selben Maske, deren Datenquelle erstellt wurde, wählt im Dropdown Menü neben „Bericht entwerfen“ „Leerer Bericht“ aus und klickt auf das Icon daneben „Export als JasperReport-Template“.

[[Datei:JasperReports-Handbuch_iReport-leeren_Bericht_erstellen.jpg]]

Diese Datei speichert man Lokal ab. Wenn das Ergebnis im Browser geöffnet wurde muss man sich den Quelltext der Seite anzeigen lassen, den Quelltext komplett markieren und kopieren ( Tastenkombination Strg + a und dann Strg + c), in einen UTF-8-fähigen Texteditor einfügen (Strg + v) und dann als eine jrxml Datei abspeichern. JR in der Endung jrxml steht für JasperReports. Damit können die Datenquellen und die Templates unterschieden werden und sogar den selben Dateinamen tragen (nur unterschiedliche Dateiendung).

Sie sollten es sich nicht zumuten und versuchen über JasperReports einen neuen Bericht zu entwerfen. Nehmen Sie immer den "leeren" Bericht aus der entsprechende Maske, da dort sehr viele Kleinigkeiten voreingestellt sind. Sie sparen sich damit immens viel Arbeit.


=== Template einbinden ===


==== Reportdesign verlinken ====

Um das erstellte Template einzubinden, muss zunächst die jrxml Datei in das Verzeichnis webapps/superx/WEB-INF/reports kopiert werden. Danach muss das Stylesheet im System bekannt gegeben werden. In Grunddaten und Basisberichte geht man dazu in „Administration“ → „Masken“ → „Stylesheet suchen“ und schickt die Maske so ab. Danach klickt man bei einem beliebigen Stylesheet auf den „bearbeiten“ Button ganz rechts in der Tabelle.

[[Datei:JasperReports-Handbuch_iReport-Stylesheet_1.jpg]]

Klickt dann auf „Neuen Datensatz erzeugen“.

[[Datei:JasperReports-Handbuch_iReport-Stylesheet_2.jpg]]

In Dateiname kommt der Dateiname der jrxml Datei rein, welche sich in dem reports Ordner befindet. Beschriftung und Beschreibung sollte eindeutig dem Stylesheet zuzuordnen sein. Für JasperReport wählt man bei „Tabelle oder Maske“ „Stylesheet für eine Ergebnistabelle“ aus. Der Dateityp stellt das default Ausgabeformat fest.

Um dieses Stylesheet nun einer Maske zuzuordnen, geht man in die Maske „Administration“ → „Masken“ → „Maske suchen“, sucht in dem Feld „Maske“ die gewünschte Maske aus und klickt dann auf „Abschicken“. Nun klickt man auf den Button Stylesheets neben der Maske, der das neue Stylesheet zugeordnet werden soll.

[[Datei:JasperReports-Handbuch_iReport-Stylesheet_3.jpg]]

In dem neuen Fenster wählt man das neu erstellte Stylesheet aus und speichert diese Einstellung ab.

[[Datei:JasperReports-Handbuch_iReport-Stylesheet_4.jpg]]

Damit ist der Bericht der Maske zugeordnet.

<blockquote>Normal wird im Servlet direkt vom Berichtsergebnis nach JasperReports übergeben, d.h. ohne den Zwischenweg XML. Wenn aber im Dateinamen *_xmlsource.jrxml steht, wird Datenquelle XML erzwungen (für Makroberichte, Unterberichte, Subdatasets oder spezielle XPATH-Selektionen wichtig).
</blockquote>

==== Nutzung des Upload Servlets ====

Wenn Sie keinen Schreibzugriff auf den Ordner ''WEB-INF/reports'' haben, können Sie auch Templates über das [http://www.superx-projekt.de/doku/kern_modul/admin/f_Anpassungderwebxml.htm Upload Servlet ]direkt im Browser hochladen. Dazu müssen Sie in der web.xml die Dateiendungen .jrxml und (sofern benötigt) .jasper erlauben, siehe obiger Link.

Danach können Sie die Report Templates hochladen:

[[Datei:JasperReports-Handbuch_jr_upload1.png]]

Nach dem Upload können Sie das Template zunächst registrieren:

[[Datei:JasperReports-Handbuch_jr_upload2.png]]

und dann der jew. Maske zuordnen. Beachten Sie, dass der Pfadname relativ zum Ordner WEB-INF/reports angegeben wird, also in der Regel

../../default/custom

bzw. beim Mandantenbetrieb

../../Mandant-ID/custom


==== Probleme beim Deployment im Server ====

Es kann u.U. beim Deployment eines Berichts im Server das Problem auftreten, daß ein Bericht im lokalen iReport mit der XML-Datenquelle funktioniert, aber im Server für einzelne Merkmale kein Ergebnis geliefert wird. Dies hat folgende Ursache:


===== Feldnamen im Berichtsdesign weichen vom Datenbank-Feldnamen ab =====

Bei der lokalen Entwicklung in iReport werden die Berichte mit der Datenquelle XML erzeugt. In den Muster-JRXML-Dateien, die man über das Feld "Bericht erzeugen" generiert, sind die Felder über die folgende Notation deklariert:

<field name="Fakultät/Fachbereich (Schlüssel)" class="java.lang.String">

<fieldDescription><![CDATA[col[@id="4" and wert!=""]/wert]]></fieldDescription>

</field>

Dies bedeutet: Das Feld "Fakultät/Fachbereich (Schlüssel)" hat den Typ "String" und befindet sich im XML-Datenstrom in der vierten Spalte (col@id=4). Dabei befindet sich in Datenblattberichten im Spaltennamen immer ein "\n" vor der Zeichenkette "(Schlüssel)", um einen Zeilenumbruch im generischen Standardlayout zu erzeugen. Dieses "\n" wird dann für iReport und JasperReports automatisch durch ein Leerzeichen ersetzt.

Wenn die XML-Datenquelle nicht verändert wird, dann ist das Feld immer mit dem gleichen Inhalt gefüllt.

Wenn man den Bericht dann auf den Server kopiert und einbindet, ohne im Dateinamen "_xmlsource" zu verwenden, dann wird das Feld nicht über die Spaltennummer identifiziert, sondern über den Feldnamen, hier z.B. "Fakultät/Fachbereich (Schlüssel)". Das bedeutet, daß der Server genau diesen Feldnamen zurückliefern muss. Das kann u.U. abweichen:

* Der Server bzw. die zugrunde liegende Maske wurde verändert, so daß der Feldname geringfügig anders ist. Das sollte eigentlich nicht passieren, kann aber vorkommen.
* Beim Betrieb in HISinOne gibt es in allen Versionen bis 3.02 noch eine kleine Veränderung, wenn das Modul des zugrunde liegenden Datenblattberichts bzw. der Maske direkt per Tomcat-Start installiert wurde, und nicht in dem Edustore-Installation/Upgrade-Menü. Wenn die Module beim Tomcat Start in eine leere Datenbank installiert werden, dann werden Zeichenketten mit dem Feldinhalt "\n" verfremdet nach "n" (also der "\" wird entfernt). Das führt dann dazu, daß das Feld ohne den "\" in der jrxml-Datei deklariert wird, also z.B.

<field name="Fakultät/Fachbereichn(Schlüssel)" class="java.lang.String">

<fieldDescription><![CDATA[col[@id="4" and wert!=""]/wert]]></fieldDescription>

</field>

Wenn man danach dann einen Upgrade der jew. Komponente ausführt, dann wird die Spalte in der Maske umbenannt nach "Fakultät/Fachbereich'''\n'''(Schlüssel)" und der Feldname korrekt nach "Fakultät/Fachbereich''' '''(Schlüssel)" umgesetzt. Durch das "n" vor der Zeichenkette "(Schlüssel)" paßt der Feldname in der jrxml-Datei nicht mehr zum Ergebnis aus der Datenbank, und das Feld ist leer. So kann es passieren, daß ein Bericht in iReport funktioniert, im Server aber nicht. Im folgenden die Lösung.


===== Korrektur der Feldnamen im Berichtsdesign =====

Um sicherzustellen, dass der Feldname der jrxml-Datei mit der jeweils aktuell benutzten Datenbank-Version übereinstimmt, geht man wie folgt vor:

* Erzeugen Sie in Edustore eine HTML-Ausgabe der zugrunde liegenden Abfrage, bei Datenblatt-Berichten ist dies das "generische Standardlayout".
* Klicken Sie dann oben im Berichtskopf auf den Button "Bericht entwerfen" -> "leerer Bericht"
* Im Quellcode sehen Sie die Zeilen <field name="Berichtsname" class="java.lang.String"> ... Hier ist jedes einzelne Feld aus der Datenbank deklariert.
* Markieren Sie alle Zeilen bis zum letzten "<field...>"-Element, i.d.R. ist dies das Feld <field name="user"..., und kopieren Sie dies in die Zwischenablage
* Öffnen Sie die jrxml-Datei mit einem UTF-8-fähigen Editor, z.B. Jedit.
* Ersetzen Sie genau die "<field..."-Passage aus der Zwischenablage.
* Speichern Sie den Bericht, und testen Sie die Vorschau in JasperReports. Wahrscheinlich kommt eine Fehlermeldung "Field ... does not exist" o.ä., dann müssen Sie das Feld mit Suchen->Ersetzen umbenennen.
* Das machen Sie so lange, bis die Vorschau funktioniert. Danach können Sie die jrxml-Datei wieder auf den Server kopieren. Die Felddeklaration passt dann zum Server.


== Zuordnung von Default-Feldbelegungen zu Stylesheets ==

Es können für Stylesheets Default-Feldbelegungen für Stylesheets hinterlegt werden. Hintergrund dieser Funktion ist, dass bei speziellen Stylesheets standardmäßig beliebig viele Spalten vorbelegt werden können. In Datenblattberichten gibt es z.B. das Feld "Felder", in dem die auszugebenden Spalten angegeben werden. Aus Performancegründen sollten nur die Spalten ausgegeben werden, die auch benötigt werden. So kann dann z.B.für JasperReport Stylesheets hinterlegt werden können, welche Spalten auf jeden Fall benötigt werden. Der Anwender weiß nicht welche Spalten benötigt werden und würde im Normalfall alle Spalten ausgeben lassen um keine Fehlermeldung zu erhalten. Dadurch würde aber wiederum der Bericht unnötig lange dauern, da alle Spalten berechnet werden müssen, auch die, welche nicht benötigt werden.

Wenn Sie ein Stylesheet erstellt haben und dieses in SuperX eingebunden haben gehen Sie wie folgt vor:

Sie gehen in die Maske "Administration -> Tabelle suchen", geben dort bei Stichwort "stylesheet_field" ein und schicken die Maske ab.

[[Datei:JasperReports-Handbuch_stylesheet_field_maske.png]]

In der folgenden Ergebnistabelle klicken Sie bei "stylesheet_field_list" auf den "Bearbeiten" Button.

[[Datei:JasperReports-Handbuch_stylesheet_field_tabelle.png]]

In dem nun geöffneten Fenster sehen Sie alle Zuordnungen, welche bereits eingetragen sind. Hier wird aber lediglich das Stylesheet ausgegeben und nicht die Tabellen und Federzugehörigkeit. Dies hätte wegen der vielen Auswahlmöglichkeiten jeden Browser gekillt. Um Einzelheiten zu erfahren müssen Sie daher auf den Details-Button klicken. Auch wenn Sie eine neue Zuordnung erstellen möchten klicken Sie zunächst auf den Detail-Button eines beliebigen Stylesheets.

[[Datei:JasperReports-Handbuch_stylesheet_field_list.png]]

Jetzt können Sie die Zugehörigkeit des Stylesheets zu Tabelle und Feld ändern oder eine neue Zuordnung erstellen.

Achtung: Wenn ein Tabellenname ausgewählt und abgespeichert wurde, können nur Spalten dieser Tabelle ausgewählt werden. Wenn Sie die Tabelle ändern wollen, müssten Sie zunächst die Tabelle ändern, abspeichern und dieses Formular erneut aufrufen. Erst dann würden die Spalten der ausgewählten Tabelle in der Listbox Fieldname erscheinen.

[[Datei:JasperReports-Handbuch_stylesheet_field_edit.png]]

Um eine neue Verknüpfung zu erstellen klicken Sie zuerst auf den + Button oben rechts. Danach erscheint das gleiche Formular nur ohne ausgefüllte Felder. Hier können Sie das Stylesheet und den Tabellennamen auswählen und die dazu passende Spalte der Tabelle die Sie zuvor ausgewählt haben. Achten Sie darauf die Tabelle zu nehmen, welche im Datenblatt verwendet wird. Danach nur noch über das Diskettensymbol oben rechts abspeichern und eine Spalten-Stylesheet-Verknüpfung ist fertig. Diesen Schritt wiederholen Sie für jede Spalte, die Sie in dem JasperReport Bericht benötigen.

Ab Kernmodul 4.2 bzw. HISinOne 5.1 geht es noch komfortabler, Sie können hier auf einzelne Stylesheets filtern : Administration → Masken → Stylesheet suchen

Wählen Sie zunächst den Bericht aus, und klicken Sie dann rechts beim Bearbeiten-Button in der Spalte Felder-Vorbelegungen bearbeiten:

[[Datei:JasperReports-Handbuch_stylesheet_field.png]]

In dem Bearbeitungsformular können Sie Datensätze erzeuge, löschen etc.


== Kurzanleitung Direktaufruf von Jasper-Berichten von der Maske ==

Nach dem Abschicken der Maske kann man auch direkt auf den entsprechenden Jasper-Bericht umgeleitet werden. Es muss dazu in der Maske ein Feld geben mit dem Namen

tablestylesheet

und der relation

<<SQL>> select distinct filename,X.caption from sx_stylesheetsX, 
sx_mask_style S where X.tid=S.stylesheet_id and S.maskeninfo_id=23880

und zum Beispiel für Default der Maske 23880

<<SQL>> select distinct filename,X.caption from sx_stylesheets X,sx_mask_style S where X.tid=S.stylesheet_id and S.maskeninfo_id=23880 and S.ord=2

Für die Anzeige des Feldes tablestylesheet im Browser wird eine Berschriftung caption hinterlegt, damit auf der Maske "Bericht" erscheint. Im neuen Kern-Modul passiert dies automatisch.

Es ist möglich einen manuellen Eintrag in die Tabelle ''sx_captions'' einzufügen (siehe Maske Administration -> Maske -> Beschriftung suchen).

{| class="wikitable"
|-
!
!
!
!
!
|-
| tid
| table_name
| field_name
| locale
| contents_short
|-
| <<wird automat. vergeben>>
| felderinfo
| tablestylesheet
| de
| Bericht
|}

Außerdem muss man die Maske um ein Feld Ausgabeformat ergänzen, das die Art=1 hat und folgende relation:

select element_value,description from menu_element where element='Ausgabeformat' and nature::smallint<100 order by nature::smallint

Beispiel für Default Excel:

<<SQL>> select element_value,description from menu_element where element='Ausgabeformat' and description='Excel'

Achtung: Hier kommen erst Ergebnisse, wenn Sie das Kernmodul 4.1 / HISinOne 3.0 oder höher installieren.


== Spezielle Variablen ==

Im Berichtsdesign können neben den Feldern der Ergebnistabelle auch z.B. der Berichtsname, Erleuterung, user und standdatum benutzt werden. Zu finden sind diese im "Report Inspector" unter Fields. Um auch Hochschulspezifische Informationen wie Hochschulname oder Hochschul-Webadresse in einen Bericht importieren zu können wurden unter anderem die sx_captions Variablen "REPORT_HEADING_INSTITUTION" und "REPORT_HEADING_URL" integriert.

[[Datei:JasperReports-Handbuch_sx_captions_markiert.png]]

Diese können genau wie die anderen Fields in den Bericht per Drag&Drop gezogen werden.


== Makroberichte als Datenquelle für JasperReports ==

Sie können als Datenquelle für JR nicht nur einzelne Masken nehmen, sondern auch die Ausgabe von Makro-Masken. Dadurch können die verschiedenartigsten Informationen aus den normalen Masken für übergreifende Berichte genutzt werden.

Das folgende Beispiel zeigt, wie im KLR-Bericht "Berichtsblatt: Kennzahlen aus der Kostenrechnung" Teile verwendet werden, um einen eigenen JR zu erzeugen, der wiederum Elemente des Makroberichts als Unterbericht nutzt.

Zunächst rufen Sie den Makrobericht auf:

[[Datei:JasperReports-Handbuch_makro_html.png]]

Das Bild zeigt die ersten drei Elemente des Makros, sie werden mit einer Ordnungsnummer durchnummeriert.

Wir laden dazu die XML-Datenquelle herunter, die XML-Datenquelle binden wir wie [[#3.1.2.Datenquelle erzeugen|outline|gewohnt]] in JasperReports ein:

[[Datei:JasperReports-Handbuch_makro_datenquelle.png]]

Dann klicken wir im Browser über den Tabellen den Button rechts von "Bericht entwerfen" → Leerer Bericht. Die JRXML-Datei speichern wir wie [[#3.1.3.Template erzeugen|outline|gewohnt]].

Im Designer sehen wir nun bei den Feldern eine erweiterte Liste:

[[Datei:JasperReports-Handbuch_makro_jrxml.png]]

Wir sehen also, daß die Ergebnisspalten mit einem Präfix für die Tabellennummer versehen sind, z.B. "tab_0". Dadurch können wir die Tabellen und somit auch die jew. Spalten eindeutig identifizieren. Dies ist gleichzeitig der Hauptbericht. Das Detail-Band löschen wir (ist nicht nutzbar), stattdessen aktivieren wir ein Summary Band.

Dann erzeugen wir den [[#2.5.Unterberichte |outline|Unterbericht]] für Studierenden-VZÄ. Dazu speichern wir die obige jrxml-Datei z.B. mit dem Namen makro_beispiel_ub_stud.jrxml und entfernen das Titel-Band und Seitenfuß-Band. Dann fügen wir im Designer einen Parameter "ordnr" hinzu:

[[Datei:JasperReports-Handbuch_makro_ub_param.png]]

Der Unterbericht bekommt dann in der Report Query folgende Änderung:

[[Datei:JasperReports-Handbuch_makro_ub_report_query.png]]

Die Ordnungsnummer wird vom Hauptbericht übergeben und dient dazu, in der XML-Datenquelle auf die einzelne Tabelle zu filtern.

Zusätzlich geben wir noch einen weiteren Filter ein, damit die Summenzeilen aus der Originaltabelle nicht in die Kreuztabelle aufgenommen werden:

[[Datei:JasperReports-Handbuch_makro_ub_filter.png]]

Damit der Unterbericht auch "stand-alone" ausführbar ist, können Sie dem Parameter "ordnr" auch einen Standardwert zuweisen, hier z.B. "2":

[[Datei:JasperReports-Handbuch_makro_ub_ordnr_default.png]]

Nun können wir die [[#2.5.Unterberichte |outline|Kreuztabelle]] mit dem Assistenten erzeugen. Für unser Beispiel enthält die Kreuztabelle Studierenden-VZÄ nach Studiengang und Fachkennzeichen:

[[Datei:JasperReports-Handbuch_makro_ub_crosstab.png]]

Wir speichern den Unterbericht und binden ihn in den Hauptbericht im Summary Band ein. Dabei vergeben wir wie gewohnt die Parameter XML_LOCALE und XML_NUMBER_PATTERN. Außerdem erzeugen wir den Parameter "ordnr", und weisen diesem den Wert 2 zu, weil die Studierenden-Tabelle die Ordnungsnummer 2 hat (s.o.):

[[Datei:JasperReports-Handbuch_makro_hauptbericht_ub_params.png]]

Damit ist die Konfiguration beendet, der Bericht sieht so aus:

[[Datei:JasperReports-Handbuch_makro_hb_erg.png]]

Weitere Unterberichte lassen sich analog hinzufügen.

<blockquote>Hinweis zum Einbinden im Servlet: Unterberichte arbeiten nur mit der Datenquelle XML, daher müssen Sie die Datei des Hauptberichts mit dem Suffix "_xmlsource" versehen.
</blockquote>


== Kompatibilität von iReport mit JasperReports ==

Wenn Sie mit iReport Berichte erzeugen, sollte wie gesagt die iReport-Versionsnr. mit der JasperReports-Version übereinstimmen, die der jew. Server nutzt. In Edustore ist dies derzeit die Version 5.1.0. Wenn die Versionsnummern nicht übereinstimmen, dürfen Sie keinesfalls die *.jasper-Dateien von dem lokalen Arbeitsplatz zum Tomcat Server kopieren.

Darüber hinaus kann es auch weitere Abhängigkeiten geben, iReport bringt ein paar mehr Bibliotheken mit, als JasperReports. Wenn Sie dann eine jrxml-Datei auf den Server kopieren, könnte es eine Fehlermeldung geben in dem Stil

java.lang.NoSuchMethodError:...

Das Vorgehen ist hier wie folgt:

* Prüfen Sie zunächst, ob Sie die jeweilige Bibliothek wirklich brauchen.
* Wenn ja, dann ermitteln Sie aus dem Namen der fehlenden Klasse den Namen der *.jar-Datei. Meist reicht es, wenn Sie den Klassennamen in einer Suchmaschine eingeben, oder in einer speziellen Java-Suchmaschine wie http://www.jarfinder.com/
* Wenn Sie die jar-Datei identifiziert haben, können Sie diese von iReport-xxx/ireport/modules/ext/ in das webapps/superx/WEB-INF/lib Verzeichns kopieren.
* Danach müssen Sie Tomcat neu starten.

<blockquote>Achtung: gehen Sie beim Kopieren in den WEB-INF/lib Ordner möglichst '''sparsam''' um: manchmal gibt es zwischen einzelnen Bibliotheken unerwünschte und unvorhersehbare Querabhängigkeiten, z.B. nutzt eine iReport-Bibliothek xy.jar eine andere Bibliothek vz.jar, welche bereits im Tomcat Server vorhanden ist – aber mit einer anderen Versionsnummer. In diesem Falle kann es zu seltsamen Phänomenen kommen, die sehr schwer zu diagnostizieren sind, bis hin zu einer Instabilität des Servers. Man muss solche Kopiermaßnahmen auf jeden Fall gründlich testen! 
Unter uns: Wir nennen Probleme, die dadurch entstehen können, die "jar-Hölle"...
</blockquote>
Im folgenden sammeln wir ein paar Beispiele für gefahrlose Kopieraktionen.


==== iReport Grafiken in JasperReports ====

Bitte vermeiden Sie, iReport-spezifische "Themes" zu benutzen (z.B. "aegean"), denn dafür würden weitere Bibliotheken benötigt. Wenn Sie z.B. die folgende Fehlermeldung bekommen, wurde ein Theme benutzt:

[[Datei:JasperReports-Handbuch_grafik_theme_error.png]]

Dann sollten Sie die Einstellung für das Objekt (hier das Theme der Grafik) wieder auf default setzen.


==== Weitere Bibliotheken von iReport ====

Bei der Meldung

java.lang.NoSuchMethodError: org.objectweb.asm.ClassWriter

sollten Sie die Bibliotheken

iReport-xxx/ireport/modules/ext/asm.jar

und zur Sicherheit auch

asm-attrs.jar

in den WEB-INF/lib-Ordner kopieren.


= Troubleshooting =


== Report Problem: Class not set for bucket: <<Variable>> ==

Das Problem tritt in iReport 4.1.1 u.a. bei Kreuztabellen auf. Bei diesem Fehler fehlt in der jrxml-datei im Element <bucketExpression> Z.B.: class="java.lang.String". Diese einfach im Editor ergänzen und es funktioniert. Beispiel:

Aus :

<bucketExpression>

wird:

<bucketExpression class="java.lang.String">


== Die jasper Datei ==

Die jasper Datei ist die kompilierte jrxml. Wenn ein Bericht übertragen werden soll, z.B. von dem Entwickler auf den Server oder von dem Development System auch das Produktivsystem immer nur die jrxml Datei übertragen, da es bei Versionsunterschieden in JasperReport zu Fehlern kommt, wenn die Kompilierte Version zur Verfügung steht. Sobald der Bericht ausgeführt wird, erstellt (kompilliert) JasperReports automatisch die jasper Datei.

Wenn die jasper Datei zur verfügung steht, wird auch nur noch diese von JasperReports verwendet und nicht mehr neu kompiliert. Falls Sie also einen Bericht weiter entwickelt haben oder eine neue Version einspielen, löschen Sie direkt die jasper Datei. Ansonsten werden die Änderungen nicht wirksam.


== Im Excel Export fehlen Felder ==

In Excel werden überlappende Elemente nicht angezeigt. Wenn also 2 Elemente übereinander liegen wird in Excel nur das oberste (welches im Vordergrund liegt) angezeigt. Hier ist besonders drauf zu achten, dass visuell 1px Abstand zwischen den Elementen Platz ist. Wenn von beiden Elementen jeweils eine Linie zu sehen ist, ist es korrekt. Wenn nicht, zählt das schon als Überlappung. Dafür im iReport Designer am besten ganz nah heran zoomen um diesen Abstand zu prüfen.

Hier ein Beispiel. Die beiden oberen Elemente überlappen, die unteren nicht:

[[Datei:JasperReports-Handbuch_ireport_excel.png]]


== Hinweis für HisInOne 7.0 Kompatibilität ==

Jrxml-Dateien, die unter iReport 4.1.3 entwickelt wurden und in HisInOne 7.1 funktionieren, können in 7.0. zur Fehlermeldung führen:

java.lang.NoClassDefFoundError: net/sf/jasperreports/compilers/GroovyEvaluator

In der jasperreports5.1.0 (hisinone 7.0) ist die Klasse GroovyEvaluator nicht enthalten, für 7.1 ist die jasperreports-6.1.0.jar enthalten, die enthält den GroovyEvaluator.

Workaround:

language="groovy"

ändern in

language="java"


== HTML Export keinen whitespace ==

Normal macht JR bei HTML-Exporten für den „Seitenumbruch“ eine Reihe von Leerzeilen. Um dies zu vermeiden, setzen Sie die Property IgnorePagination=true:

<jasperReport xmlns="http://jasperreports.sourceforge.net/jasperreports" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://jasperreports.sourceforge.net/jasperreports http://jasperreports.sourceforge.net/xsd/jasperreport.xsd" name="Kaufm. Quartalsbericht" language="groovy" pageWidth="2925" pageHeight="565" orientation="Landscape" columnWidth="2925" leftMargin="0" rightMargin="0" topMargin="0" bottomMargin="0"

isIgnorePagination="true">


== UUID's ==

In Jaspersoft Studio wird an jedes Element eine lange UUID angehängt, in aktuellen Versionen von SuperX/ Edustore macht das keine Probleme. In älteren Versionen bzw. in iReport 4.* schon. Damit der JasperReport abwärtskompatibel ist, muss diese gelöscht werden. Bei großen Berichten taucht diese aber unter Umständen mehrere hundert Mal auf. Hier kann in JasperSoft Studio in dem "Source"-Reiter des Berichtsdesigners nach folgender Regular Expression gesucht werden und diese mit einem Leerzeichen ersetzt werden:

uuid="[0-9a-z-]{36}"


= Weitere Dokus =

<blockquote>Ahammad, S. (2010). iReport 3.7.Learn how to use iReport to create, format, and export reports. Birmingham: Packt
</blockquote>
<blockquote>Haneke, U. et al. (2010). Open Source Business Intelligence. Möglichkeiten, Chancen und Risiken quelloffener BI-Lösungen. Wien: Hanser
</blockquote>
<blockquote>Toffoli, G. (2007). The definitive guide to iReport. Berkeley, CA: Apress
</blockquote>
<blockquote>Noch mehr Infos (nur Englisch) erhält man unter: 
http://jasperforge.org/plugins/project/project_home.php?projectname=ireport
</blockquote>
<blockquote>und natürlich unsere Website:
</blockquote>
<blockquote>http://www.superx-projekt.de/doku/entwicklung/iReport-Handbuch/main.htm
</blockquote>
<blockquote>
</blockquote>

Berichtsdesign mit JasperReports

2026-07-06T06:26:30Z

Andrek: Die Seite wurde neu angelegt: „Berichtsdesign mit JasperReports von Daniel Quathamer & Andre Knieschewski = JasperReports installieren und konfigurieren = == Voraussetzungen == * Jasperreports ist eine Laufzeitumgebung fürs Reporting, die in java-basierte Reporting Software integriert werden kann. Der Download ist hier: https…“

Berichtsdesign mit JasperReports

von Daniel Quathamer & Andre Knieschewski


= JasperReports installieren und konfigurieren =


== Voraussetzungen ==

* Jasperreports ist eine Laufzeitumgebung fürs Reporting, die in java-basierte Reporting Software integriert werden kann. Der Download ist hier: https://sourceforge.net/projects/jasperreports/. Dieses Paket enthält kommandozeilenbasierte Demos und die benötigten Libraries. Die Demos sind sehr nützlich und als Referenz gut nutzbar.
* Die Entwicklungsumgebung für JasperReports heißt "Jaspersoft Studio" und kann bezogen werden von https://community.jaspersoft.com/project/jaspersoft-studio. Es enthält auch obige Laufzeitumgebung. 
Da es ein Eclipse Plugin ist, können Sie es auch direkt in Ihrem Eclipse installieren (Menü Help → Eclipse Marketplace → Suchwort "Jaspersoft". Dort können Sie aber nur die jeweils aktuelle Version installieren.

Da der Download bei Jaspersoft nun nur für registrierte Nutzer zur Verfügung steht, hier noch ein Link für den Download: https://sourceforge.net/projects/jasperstudio/files/

* Für altere Projekte wurde auch iReport verwendet. Da es ein paar Bugs in den verschiedenen Versionen gibt, empfehlen wir zu der Erstellung von JasperReport Berichten die iReport Version 4.1.3, auch wenn in Edustore die Version 5.1.0 verwendet wird. Download der passenden Version von iReport von http://sourceforge.net/projects/ireport (dort auf "files"->"iReport" klicken, dann erhalten Sie Links auf die jeweilige Version.
* Für Demos & Deployment auch Apache ANT http://ant.apache.org/
* Java 1.8 JRE oder höher


== JasperReports und Jaspersoft Studio ==

JasperReports ist das Programm, das fertige Berichte erzeugen kann. Es besitzt (außer einer Vorschauansicht der Berichte) keine graphische Oberfläche. Für das Entwerfen von Berichten ist ''''''Jaspersoft Studio'''''' geeignet. Um es noch ein wenig zu veranschaulichen könnte man sagen, dass wenn ein JasperReport das Worddokument wäre, dann wäre Jaspersoft Studio z.B. Microsoft Word.


=== Jaspersoft Studio ===

Nach dem Download benötigen Sie Java 1.8 oder höher zum Ausführen. Nach dem Entpacken können Sie die Anwendung direkt starten.

Bei JasperSoft Studio wird als Grundlage Eclipse verwendet. Wenn man JasperSoft Studio herunter lädt, erhält man automatisch Eclipse mit dabei. JasperSoft Studio kann [http://community.jaspersoft.com/project/jaspersoft-studio hier] heruntergeladen werden.

Wenn lieber ein bereits vorhandenes Eclipse verwendet werden soll und Jaspersoft Studio dort als Plugin installiert werden soll, gibt es 2 Wege:

<ol style="list-style-type: decimal;">
<li>Unter Help → Eclipse Marketplace kann nach „Jaspersoft“ gesucht werden und das Plugin installiert werden
[[Datei:JasperReports-Handbuch_jaspersoftstudio_plugin_install1.png]]</li>
<li>Man kann auch über die Marketplace Webseite von Eclipse das Plugin Jaspersoft Studio suchen und das Icon per Drag&Drop nach Eclipse ziehen. Dann wird das Plugin automatisch installiert. [https://marketplace.eclipse.org/content/jaspersoft-studio Hier] die Webseite. (Bei mir hat das Drag&Drop leider nicht funktioniert. Das kann an Linux liegen. Unter Windows wird es sicherlich funktionieren.)</li></ol>


==== Jaspersoft Studio Einstellungen ====

Unter Windows - > Preferences → Jaspersoft Studio können Sie verschiedene Einstellungen vornehmen. Wichtig in der Menüpunkt "Compatibility": wählen Sie dort die JR-Version, die auch Ihre Ziel-Platform enthält.

Im Dateimanager von JasperSoft Studio gibt es Eclipse-typisch ein "virtuelles" Dateisystem mit dem Standardnamen "MyReports", zumindest beim Speichern von Dateien. Dieses Dateisystem liegt physisch im Ordner <<Home-Verzeichnis>>/JaspersoftWorkspace/MyReports.

Beim Öffnen von Dateien können Sie direkt mit "Open File" aufs normale Dateisystem zugreifen.


==== Jaspersoft Studio Entwurfsbereich ====

Hier eine Übersicht des Entwurfsbereichs, in rot finden Sie Erläuterungen:

[[Datei:JasperReports-Handbuch_jaspersoft_designer.png]]

Die Unterfenster können Sie Eclipse-typisch beliebig anordnen. Oben ein Beispiel.


===== Jaspersoft Studio Sortierung und Filterung der Datenquelle =====

Wenn die Datenquelle definiert ist, kann /sollte der Bericht die Sortierung und Filterung der Daten festlegen. Dies ist etwas versteckt im Designer mittig oberhalb des Entwurfsbereichs:

[[Datei:JasperReports-Handbuch_jaspersoft_design_query.png]]

Im "Dataset and Query Dialog" sind die Felder der Datenquelle aufgeführt. Unten finden Sie die Reiter "Sorting" und "Filter Expression". Dort pflegen Sie beides.


===== Jaspersoft Studio Berichtsdesign und Vorschau =====

Im Designmodus können Sie den Bericht entwerfen, oder den XML-Quellcode. Beim Klick auf den Reiter "Preview" bekommen Sie eine Vorschau des Berichts:

[[Datei:JasperReports-Handbuch_jaspersoft_design_preview.png]]

Oberhalb der Vorschau können Sie die Datenquelle (d.h. den "Data Adapter" angeben, und rechts daneben die Anwendung, die den Bericht zur Anzeige bringt ("Viewer"). Voreingestellt ist hier der Java-interne Viewer von JasperReports, Sie können den aber umstellen z.B: auf PDF oder Excel.

Mit Klick auf das grüne Dreieck führen Sie den Bericht aus und erhalten die Vorschau.

<blockquote>Achtung: Es ist aufgefallen, dass beispielsweise Fettdruck in der PDF-Vorschau nicht angezeigt wird. Im Java-Preview und aus der Weboberfläche geladen, ist der Fettdruck ersichtlich.
</blockquote>

===== Jaspersoft Studio Berichtsstruktur =====

Im "Outline View" sehen Sie die Struktur des Berichts, d.h. aktive "Bänder" und Metadaten:

[[Datei:JasperReports-Handbuch_jaspersoft_design_outline.png]]

Die Elemente unter "Fields" werden bei Nutzung in [[#3.1.3.Template erzeugen|outline|Edustore]] automatisch gefüllt. Alles weitere definieren Sie.


===== Jaspersoft Studio Elemente bearbeiten =====

Wenn Sie im Design Modus ein Element markieren, wird es automatisch im Outline und in dem Reiter "Properties" selektiert:

[[Datei:JasperReports-Handbuch_jaspersoft_design_properties.png]]

Im Outline zeigt es lediglich, wo es sich befindet, und im Reiter "Properties" können Sie Formatierung, Anzeige etc. bearbeiten.


=== iReport ===

[[Datei:JasperReports-Handbuch_welcome.png]] Das Paket enthält bereits die Laufzeitumgebung JasperReports, diese muss also nicht separat installiert werden. Nichtsdestotrotz empfiehlt sich der Download, denn in dem JasperReports-Paket befinden sich viele lehrreiche Demo-Berichte.

Die Windows-Version beinhaltet auch einen Installer. Um diesen zu nutzen sind Admin-Rechte erforderlich.

Alternativ bzw. unter Linux ist iReport ohne Installation direkt nach dem Entpacken lauffähig. Wenn Sie auch Scriptlets erstellen wollen, müssen Sie nicht nur eine Java-Laufzeitumgebung (JRE) installieren, sondern ein JDK, und die Datei $JAVA_HOME/lib/tools.jar nach iReport-<<Versionsnr.>>/ireport/libs kopieren. Danach müssen Sie iReport neu starten.

Start unter Windows: iReport-<<Versionsnr.>>/bin/ireport.exe

Start unter Linux: iReport-<<Versionsnr.>>/bin/ireport


==== iReport Einstellungen ====

Als erstes sollten Sie die Anwendungen einstellen, mit denen iReport generierte Berichte anzeigen soll:

Im Menü Extras-> Optionen wählen Sie im Reiter "iReport"-"Viewers" die entsprechenden Anwendungen:

[[Datei:JasperReports-Handbuch_ireport_viewers.png]]


==== iReport Entwurfsbereich ====

Der Entwurfsbereich bzw. "Designer" hat einen recht komplexen Aufbau. Sie können die Fenster und Seitenbereiche zwar recht flexibel anpassen, aber hier ist die Auslieferung:

[[Datei:JasperReports-Handbuch_designer_ueberblick.png]]

Die wichtigen Bereiche sind hervorgehoben:

* Berichtsstruktur: Welche Seitenbereiche gibt es?
* Datenquelle: Welche Datenbank wird genutzt?
* Abfrage: Was ist die konkrete Abfrage für den Bericht?
* Elemente: Welche Elemente kann ich einfügen, und welche Eigenschaften haben sie?
* Vorschau: wie sieht der Bericht "gedruckt" aus?
* Fehlerausgabe: Jeder Bericht wird "kompiliert", dazu gibt es eine Fehlerausgabe

Im Reiter "Preview" kann man sich eine Vorschau des Ausdrucks anzeigen lassen.


=== Unterschiede iReport und JasperSoft Studio ===

Mit der Version 5.5 wurde die Entwicklung von iReport eingestellt, die Firma JasperSoft empfiehlt seit dem die Benutzung von JasperSoft Studio. Nach unseren Erfahrungen ist die Arbeit mit iReport 4.1.3 (die letzte stabile Version) hier und da "leichtgewichtiger" und einfacher, ganz zu schweigen vom Overhead, den JasperSoft Studio mit Eclipse einbringt. Besonders nervig empfanden wir es, dass JasperSoft Studio anders als iReport verschiedene Objekteigenschaften in Reitern organisiert, und bei jedem Wechsel der Markierung eines Berichtselements muss man in JasperSoft Studio wieder zum richtigen Reiter wechseln.

Andererseits ist JasperSoft Studio kompatibel mit neueren JR-Möglichkeiten. Insbesondere bei dem Umgang mit Diagrammen gibt es in JasperSoft Studio erheblich mehr Möglichkeiten, z.B. Chart Customization. Außerdem ist es vorteilhaft, wenn Sie ohnehin Eclipse nutzen. Sie sollten für Ihre Arbeit also abwägen ob Sie die neueren Möglichkeiten im jeweiligen Bericht überhaupt brauchen, ggf. sind Sie mit iReport besser bedient. Aber das ist Geschmackssache.

<blockquote>Beachten Sie aber bitte: sobald Sie einen Bericht mit JasperSoft bearbeitet und gespeichert haben, ist er mit iReport 4.1.3 nicht mehr bearbeitbar, bzw. nur wenn Sie die [[#4.6.UUID's|outline|UUIDs]] entfernt haben.
</blockquote>
Beide Produkte befinden sich noch im Einsatz, daher hier nur ein paar Kapitel zur Handhabung der jew. Software.


==== Handhabung ====


===== Preview =====

Bei iReport waren die Buttons für Designer und Preview immer oben.

[[Datei:JasperReports-Handbuch_jss-ir_preview1.png]]

Bei Jaspersoft Studio liegen die Buttons unten:

[[Datei:JasperReports-Handbuch_jss-ir_preview2.png]]


===== Palette =====

Die Palette ist bei iReport und Jaspersoft Studio an gleicher Position zu finden.

Ireport:

[[Datei:JasperReports-Handbuch_jss-ir_palette1.png]]

Jaspersoft Studio:

[[Datei:JasperReports-Handbuch_jss-ir_palette2.png]]


===== Objekt-Eigenschaften =====

Die Objekt-Eigenschaften liegen auch an der gleichen Stelle, jedoch sind bei Jaspersoft Studio die Gruppierungen der Eigenschaften in Karteireiter unterteilt. Bei iReport ist es einfach eine lange Liste mit Unterteilungen.

iReport:

[[Datei:JasperReports-Handbuch_jss-ir_properties2.png]]

Jaspersoft Studio:

[[Datei:JasperReports-Handbuch_jss-ir_properties1.png]]


== JasperReports als Kommandozeilen-Tool ==

In der JasperReports-Distribution befindet sich ein ANT-Script, das mehrere Berichte erzeugen kann.

cd demo/samples

Beispiel xmldatasource:

cd xmldatasource

ant -p

Die Ausgabe ist:

[[Datei:JasperReports-Handbuch_ant_xmldatasource.png]]

Es werden, je nach Auswahl pdf-, Excel- oder andere Berichte erzeugt. Mit dem Target "test" werden alle Targets durchlaufen.

ant test

Achtung: manche Demos brauchen eine laufende HSQLDB (siehe demo/hsqldb).


= Datenquellen =

Allgemein unterstützt JasperReports verschiedene Datenquellen, z.B. relationale Datenbanken, Excel, CSV oder XML. Auch Webservices sind möglich. Speziell für SuperX/ HISinOne-BI gibt es spezielle Datenquellen-Vorgaben, damit Sie die Daten auch im Server-Betrieb nutzen können. Hier also nur die allgemeinen, also SupeRX/BI-unabhängigen Quellen, wenn Sie JasperReports am lokalen Arbeitsplatz nutzen.


== Datenquelle Datenbank ==

Eine relationale Datenbank ist in JasperSoft Studio als "Data Adapter" einzurichten. Oben links befindet sich der Dialog zum Erzeugen (1) des Data Adapter, und dann darunter die Zeile "Database Jdbc Connection" (2):

[[Datei:JasperReports-Handbuch_data_adapter1.png]]

Dort geben Sie dann die jdbc-spezifischen Daten an (Datenbanktyp, Name etc.).

<blockquote>Achtung: die Nutzung setzt eine direkte Datenbankverbindung zum DB-Server voraus, an vielen Unternehmenanwendungen wird dies nicht mehr erlaubt. Ggf. fragen Sie bei Ihren Systemadministrator/innen nach.
</blockquote>


== Datenquelle Excel-Datei ==

Eine Excel Datei ist in JasperSoft Studio als "Data Adapter" einzurichten. Hier ein Beispiel:

[[Datei:JasperReports-Handbuch_datenquelle_excel_1.png]]

Die Excel Datei hat vier Spalten und eine führende Zeile mit den Spaltenüberschriften. Achten Sie darauf, dass die Datentypen der Spalten in Excel dem Inhalt entsprechen. Hier die Spalten:

* Frage Nr.
* Text
* Mit_ohne_schule
* Summe

Aus der Excel-Datei erzeugen Sie einen "Data Adapter". Der Data Adapter vom Typ "Excel File" hat ein paar Eigenschaften:

[[Datei:JasperReports-Handbuch_datenquelle_excel_2.png]]

Danach können Sie in einem Berichtsdesign die Datenquelle definieren:

[[Datei:JasperReports-Handbuch_datenquelle_excel_5.png]]

Sie wählen dort oben links zunächst den "Data Adapter" aus (1), und klicken dann rechts auf "Read Fields" (2):

[[Datei:JasperReports-Handbuch_datenquelle_excel_3.png]]

Aus der Datenquelle werden dann die Datenfelder (3) und Inhalte (Reiter "Data preview") automatisch übernommen.


= Berichtsdesign =

Das Erstellen eines Berichtes erleichtert JasperReports wesentlich. Dennoch wird man sich damit etwas beschäftigen müssen, um ein vernünftiges Ergebnis zu erhalten.

Zuerst muss man den Bericht öffnen. Das geschieht über „Datei“ → „Open“ → Bericht auswählen → auf „Öffnen“ klicken. Nun noch oben links die für diesen Bericht erstellte Datenquelle auswählen und man kann loslegen.

JasperReports bezeichnet die Ausgabebereiche als Bänder. Ein Band ähnelt einer Zeile. Es reicht über die komplette Seitenbreite. Die Höhe kann dabei selbst bestimmt werden und wird dem Informationsgehalt angepasst. Das Band „Detail 1“ ist so etwas wie das Hauptband, in dem dann die Informationen zeilenweise ausgegeben werden. Es wird also eine Schleife über die Daten (Tabelle) ausgeführt und für jeden Datensatz ein mal das Detail Band ausgegeben. Die linke Spalte könnte z.B so aussehen:

[[Datei:JasperReports-Handbuch_iReport-iReport_Leiste_Neu.jpg]]

Hier sieht man, das das Band „Detail 1“ aktiv ist und die anderen wie „Title“ noch nicht. In den Gruppen „Fields“ und „Variablen“ befinden sich die Felder (Spalten) aus der Ergebnistabelle und interessante Variablen wie Seitenzahl, die man nun einfach in das bestehende Band „Detail 1“ per „Drag and Drop“ ziehen kann.

[[Datei:JasperReports-Handbuch_iReport-Feld_Name.jpg]]

Wenn man z.B. in der Gruppe Fields das Feld „Name“ hat und dies in das Band „Detail 1“ zieht,befindet sich ein Platzhalter im Entwurfsbereich:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_1_Namen.jpg]]

Wenn Sie dann auf „Preview“ klicken, wird eine Vorschau des Berichts angezeigt.

[[Datei:JasperReports-Handbuch_iReport-Designer_Preview.jpg]]

Es werden alle Namen aufgelistet, die in der Datenquelle vorhanden sind:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_1_Namen_Ergebnis.jpg]]

Sie können das Layout der Ausgabe (Schriftart, Größe) über die Eigenschaften des Feldes variieren.

Um wieder zurück in den Entwicklermodus zu kommen klickt man einfach wieder auf den Reiter "Designer".

Die Bänder „Title“, „Page“ usw. kann man mit einem Rechtsklick und dann „Add Band“ hinzufügen und auch wieder mit einem rechtsklick und dann „Delete Band“ wieder entfernen. Diese Bänder haben bestimmte Eigenschaften. Z.B. Band „Titel“ wird nur einmal auf der ersten Seite abgebildet, Band „Page Header/Footer“ auf jeder Seite am Anfang/Ende.


== Sortierung und Filtern ==

Normalerweise verarbeitet JasperReports die Datensätze zeilenweise in der Reihenfolge, in der sie bereitgestellt werden. Sie können im Entwurfsmodus die Sortierung bzw. Filterung der Datensätze anpassen:

[[Datei:JasperReports-Handbuch_ireport_sort1.png]]

Klicken Sie auf das Icon mit der Tonne und Sie gelangen in die Einstellungen für die Datenquelle.

[[Datei:JasperReports-Handbuch_ireport_sort2.png]]

Im Button Sortieren können Sie nach allen Feldern des Berichts aufsteigend bzw. absteigend sortieren.

[[Datei:JasperReports-Handbuch_ireport_sort3.png]]

Im Button "Filter expression" können Sie eine Formel definieren, um die Gültigkeit von Datensätzen zu definieren:

[[Datei:JasperReports-Handbuch_ireport_filter1.png]]

Z.B. die Expression ".contains("12") würde auf alle Datensätze filtern, die im Feld die Zeichenkette "12" enthalten. Weitere Infos im Kapitel zum [[#2.9.Expression Editor|outline|Expression Editor]].


== Listen ==

Listen lassen sich einfach erstellen, indem man die jeweiligen Felder ins Detail-Band zieht. Manchmal kann es vorkommen, dass Textfelder "überlaufen", d.h. die rechteckige Box, die das Feld markiert, ist zu klein für den Feldinhalt. Beispiel:

[[Datei:JasperReports-Handbuch_listen_stretch.png]]

In diesem Falle muss man das Attribut des jew. Felder (hier "Fächergruppe") "Text Field properties > Stretch with overflow" ankreuzen.

Achtung: wenn das Feld Teil einer tabellarischen Auflistung ist, muss man die anderen Element mit der Eigenschaft "Stretch type → Relative to tallest object" versehen, hier z.B. die Felder "Studienfeld" und "Studienbereich".

Bei vielen Zeilen ist es übersichtlicher, jede zweite Zeile farbig zu hinterlegen. Dieser Trick ist im Abschnitt Tabellengestaltung [[#2.4.3.Zeilen alternierend einfärben|outline|erläutert]].


== Gruppierung ==

Wichtige Vorbemerkung zum Gruppieren: JasperReports setzt bei der Gruppierung voraus, dass die Datensätze der Datenquelle nach den Gruppierungsmerkmalen sortiert sind. Alle Merkmale, nach denen Sie gruppieren, sollten also entweder direkt in der Datenquelle sortiert sein, oder in JasperReports im [[#2.1.Sortierung und Filtern|outline|Berichtsentwurf]].


=== Gruppen definieren ===

Zu den Standardbändern kann man nun auch noch selbst definierte Gruppen hinzufügen. Mit einem Rechtsklick auf den obersten Knoten → „Add Report Group“ öffnet sich ein Fenster in dem man der Gruppe einen Namen geben kann und das Objekt wählt für das die Gruppe erstellt wird.

[[Datei:JasperReports-Handbuch_designer_add_group.png]]

<blockquote>Achtung: wenn Sie mehrere Gruppierungsebenen benötigen, dann sollte die Reihenfolge des Hinzufügens der Gruppen "top-down" verlaufen, d.h. zuerst die oberste Gruppierung hinzufügen, dann die Gruppe darunter usw.
</blockquote>
In dem folgenden Beispiel wird die Gruppe „Monat“ gewählt und in dem nächsten Schritt mit Header und Footer hinzugefügt:

Man zieht das Feld „Namen“ in das Band „Detail“ und „Monat“ in das erstellte Band „Monat Group Header 1“. Aus der Palette rechts oben (wenn nicht vorhanden bekommt man es über „Fenster“ → „Palette“) zieht man einen „Static Text“ in das Band „Monat Group Header 1“ vor der Ausgabe des Monats, benennt das Feld „Monat:“ und noch eine Linie darunter. Zusammen sollte es so aussehen:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_Monat_Namen.jpg]]

Wenn man nun auf „Preview“ klickt erhält man als Ergebnis:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_Monat_Namen_Ergebnis.jpg]]


=== Seitenumbrüche ===

Damit eine Gruppe nicht durch einen Seitenumbruch auseinandergerissen wird, gibt es einige Einstellungen in dem Band der Gruppe. Dazu einfach auf das jeweilige Band klicken, für welches die Einstellungen vorgenommen werden sollen und dann in „Eigenschaften“ → „Group properties“ → „Keep Together“ anklicken oder wenn man möchte „Reprint header“ um den "Header" der Gruppe am Seitenkopf zu wiederholen.

Sie können auch angeben daß vor jedem Gruppierungswechsel ein Seitenumbruch ausgeführt wird:

[[Datei:JasperReports-Handbuch_designer_add_group_new_page.png]]

Mit "Start on a new page" wird eine neue Seite bei jedem Gruppenwechsel begonnen. Speziell beim Export nach Excel kann dies in Tandem mit Arbeitsblättern nutzen, siehe [[#2.19.2.Excel-Export in einzelne Tabellenblätter|outline|unten]].


=== Gruppensummen ===

Gruppensummen kann man im Kopf oder Fuß einer Gruppe anlegen. Sie aktivieren z.B. den Gruppenfuß im Report Inspector, und ziehen dann das Feld Summe in den Entwurfsbereich. Beim "Fallenlassen" werden Sie gefragt, ob Sie den jew. Wert oder eine Aggregatfunktion nutzen wollen. Für Zwischensummen wählen Sie "Sum":

[[Datei:JasperReports-Handbuch_designer_add_group_foot1.png]]

Im Entwurfsbereich setzen Sie noch ein Label bzw. "Static Text"-Element rechtsbündig davor, und setzen beide Elemente fett:

[[Datei:JasperReports-Handbuch_designer_add_group_foot2.png]]


=== Gruppierung ohne eigenes Band ===

Bei der Gruppierung in JasperReports wird in der Regel ein horizontales Band für die Gruppierungsebene angelegt. Das führt dazu, daß man zeilenorientiert gruppiert. In manchen Fällen kann es gewünscht sein, in den Spalten einer Tabelle zu gruppieren. Hier ein Beispiel für das Ziel:

[[Datei:JasperReports-Handbuch_gruppierung_spalten1_vorlage.png]]

In dem Beispiel wird in den Zeilen nach dem Merkmal '''Fach''' gruppiert. Zusätzlich wird noch in den Spalten nach Fachsemestern gruppiert. Um dieses Layout zu realisieren, muss man wie folgt vorgehen:

Erzeugen Sie ein Column Header Band, und ein Group Footer-Band für die Gruppierungsebene Fach. Warum Group Footer? Weil innerhalb des Fachs nochmal gruppiert werden soll, und daher erst nach dem Gruppieren nach Fach nach Fachsemestern gruppiert wird. Ein Detail-Band gibt es hier nicht.

[[Datei:JasperReports-Handbuch_gruppierung_spalten3_band.png]]

Erzeugen Sie eine neue Variable z.B. mit dem Namen "fs1" für erstes Fachsemester, und geben Sie der Variable folgende Eigenschaften:

[[Datei:JasperReports-Handbuch_gruppierung_spalten2_variable_1fs.png]]

Zur Erläuterung: Die Variable filtert die Datensätze gemäß dem Ausdruck in Variable Expression, und tut dies auf der Gruppierungsebene "fach". Die Variable Expression ist eine für unsere Zwecke sehr nützliche Java-Kurzfassung einer IF-THEN-Bedingung, und meint:

<blockquote>Wenn der Inhalt des Feldes "Anzahl Fachsemester" gleich 1 ist, dann gib die Summe der jew. Studierenden aus, wenn nicht, dann gib 0 aus.
</blockquote>
Analog kann man noch die Variable "fsgr13" für "Fachsemester > 13" anlegen.

Danach kann man die Variablen "fs1" und "fsgr13" in das Band "Fach Group Footer 1" ziehen, und noch das Feld "Summe" für die Gesamtsumme. Dann tragen wir im Column Header Band noch die Spaltenüberschriften ein. Insgesamt sieht Berichtsentwurf dann so aus:

[[Datei:JasperReports-Handbuch_gruppierung_spalten4_band.png]]

Und das Ergebnis sieht so aus:

[[Datei:JasperReports-Handbuch_gruppierung_spalten5_band.png]]

Fertig. Man könnte nun noch weitere Fachsemester-Intervalle einfügen, oder z.B. eine Summe der Studierenden in der Regelstudienzeit.


=== Gruppierung mit virtuellen Dimensionen ===

Wenn Sie nach Feldern gruppieren wollen, die es in Ihrer Datenquelle gar nicht gibt (z.B. nach Aggregationen von Mekrmalskombinationen), dann können Sie auch Variablen mit speziellen Formeln anlegen, und diese dann in die Gruppierung aufnehmen.

<blockquote>Wichtig: Wenn die Gruppierungsvariable nicht im Summary Band genutzt wird, muss der resettype der Variable auf „None“ gesetzt werden.
</blockquote>
Im Abschnitt zu [[#2.5.4.Kreuztabellen mit virtuellen Dimensionen|outline|Kreuztabellen]] wird z.B. gezeigt, wie die Fächer Mathe, Physik und Biologie in einen neuen Wert "Naturwissenschaften" transformiert werden.


=== Variablen und Gruppierung ===

Beim Anlegen von Gruppen-Bändern und beim Ziehen von Feldern in das jew. Gruppenband legt JR automatisch eine Variable an, mit der jew. Aggregationsfunktion. Diese Variable hat folgende Eigenschaften:

Expression: das Feld, aus dem die Variable gespeist wird

Calculation: Die Aggregatfunktion, z.B. "sum"

Reset Type: Die Gruppierungsebene

Wenn Sie die Variable in Textfeldern des Gruppenbandes nutzen, gibt sie jeweils den richtigen Wert an, egal ob Gruppenkopf oder Fuß.

Wenn Sie aber mit "Print-when-Expressions" im Gruppenband arbeiten und auf die Variablen zugreifen, funktionieren diese standardmäßig nur im Gruppenfuß, weil erst am Ende der Gruppe der Wert bekannt ist. In diesem Fall müssen Sie der Variable auch eine "Initial Value Expression" mit dem jew. Feld geben.


=== Berechnungen auf Gruppenebene ===

Wenn Sie auf der Gruppenebene Berechnungen, z.B. Mittelwerte, durchführen wollen, gibt es einige Fallstricke:

* Die in JR eingebauten Funktionen wie "avg" arbeiten auf Gruppenebene nicht immer exakt.
* Komplexere Formeln auf Gruppenebene in Variablen abzubilden und diese dann das Quelle für Textfelder zu nehmen hat bei uns nicht geklappt.

Hier unser Vorgehen:

* Definieren Sie auf der Ebene der jew. Gruppe eine Variable mit der Gesamtsumme, und eine mit der Summe der zu mittelnden Werte. Diese Variablen haben als "reset Type" die jew. Gruppierungsebene.
* Im Textfeld, das Sie ausgeben, verwenden Sie dann die Berechnungsformel, z.B. einen Quotienten. Verwenden Sie für die Berechnung nicht eine neue Variable, sondern fügen Sie die Formel direkt in das Textfeld ein.

Im folgenden ein Beispiel: Wir haben eine Absolventenliste pro Studiengang und Semester, darin werden dann Mittelwerte von Abschlussnoten gebildet. Die Datenquelle hat summierte Zeilen pro Note:

[[Datei:JasperReports-Handbuch_notenschnitt_daten.png]]

Im obigen Beispiel haben wir in der Zeile 5 eine Absolventin mit der Note 1,1. In der letzten Zeile haben wir zwei Absolventinnen mit der Note 1,2.

Würden wir den Notenschnitt manuell berechnen, müßten wir die Notensumme (Spalte H*K) ermitteln, hier wäre der Wert 32,3. Die Summe der Absolventen in Spalte K wäre 16, d.h. der Notenschnitt wäre 32,3/16 = 2,02.

In JasperReports wäre der Entwurf wie folgt:

[[Datei:JasperReports-Handbuch_notenschnitt_design1.png]]

Wir haben eine Variable "Summe_1" auf der Ebene des Semester-Bandes, die im obigen Excel der Summe der Spalte "Summe" entspricht.

Außerdem haben wir eine Variable "Notensumme" mit der Formel $F{Note}*$F{Summe}, auf der Ebene der Gruppe "Semester". Achten Sie drauf, dass Sie als Typ "java.lang.Double" nehmen, damit Sie keine Rundungsfehler bekommen.

Der Quotient wird dann im Textfeld gebildet, das den Notenschnitt auf Semesterebene enthält, und auf zwei Nachkommastellen gerundet:

[[Datei:JasperReports-Handbuch_notenschnitt_design2.png]]

Das Textfeld selbst muss bei "Evaluation time" den Wert "Group" haben, und bei "Evaluation group" dann den Wert der Gruppe "Semester". Und hier das Ergebnis in der Vorschau:

[[Datei:JasperReports-Handbuch_notenschnitt_vorschau.png]]

Der Wert 2,02 stimmt mit unserer manuellen Berechnung überein.


== Tabellengestaltung ==


=== Summen, Seitenzahlen ===

Um es noch ein wenig interessanter zu gestalten fügt man noch das Gehalt hinzu, summiert es für die Monate und gesamt. Dazu noch die Seitenanzahl und einen Seitenzähler und eine Überschrift.

Das Gehalt bekommt man, indem man das Gehalt aus den Feldern neben den Namen zieht. Das selbe macht man auch nochmal in das Band „Monat Group Footer 1“ und wählt hier die Aggregation „Sum“ aus, um die Summe zu erhalten.

Um einen Seitenzähler zu erhalten fügt man zunächst das Band „Page Footer“ hinzu und legt dort die Variable „PAGE_NUMBER“ ab.

[[Datei:JasperReports-Handbuch_iReport-Page_Number.jpg]]

Unter „Eigenschaften“ → „Text field properties“ → „Evaluation Time“ wählt man hier „Now“ um die aktuelle Seitenanzahl zu bekommen und „Report“ um die gesamte Seitenanzahl zu erhalten. In dem Beispiel ist die Ausgabe z.B.: „Seite 2 von 6“.


=== Seitenumbrüche steuern ===

Damit die drei Personen im Monat 2 nicht durch einen Seitenumbruch auseinandergerissen werden, gibt es einige Einstellungen in dem Band der Gruppe. Dazu einfach auf das jeweilige Band klicken, für welches die Einstellungen vorgenommen werden sollen (hier „Monat“) und dann in „Eigenschaften“ → „Group properties“ → „Keep Together“ anklicken oder wenn man möchte „Reprint header“ um den "Header" der Gruppe am Seitenkopf zu wiederholen.

Beispiel im Designermodus:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_2_Monat_Namen.jpg]]

Beispiel im Preview:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_2_1_Monat_Namen_Ergebnis.jpg]]

[[Datei:JasperReports-Handbuch_iReport-Beispiel_2_2_Monat_Namen_Ergebnis.jpg]]


=== Zeilen alternierend einfärben ===

Um nun bei mehreren Datensätzen auch noch den Überblick in den Zeilen zu behalten kann man jetzt auch noch den Hintergrund der Zeile abwechselnd farbig gestalten. Dazu Zieht man aus den „Reports Elements“ das „Rectangle“ in das „Detail 1“ Band

[[Datei:JasperReports-Handbuch_iReport-Even_Odd_2.jpg]]

und passt es der Größe des Bandes an.

[[Datei:JasperReports-Handbuch_iReport-Even_Odd_1.jpg]]

Die Hintergrundfarbe kann man nun in den Eigenschaften in „Backcolor“ ändern. Damit dies nun nicht in jeder Zeile erscheint, sondern abwechselnd, fügt man noch in den Eigenschaften in „Print When Expression“ den Wert Boolean.valueOf( $V{PAGE_COUNT}.intValue() % 2 == 0 ) ein.

Zur erläuterung:

Die Variable „PAGE_COUNT“ zählt die Anzahl der Datensätze hoch. Mit „% 2“ wird diese Variable durch 2 geteilt und nur der Restwert ausgegeben. Als Ergebnis erhält man also in jeder ungeraden Zeile eine 1. Dieses Ergebnis wird nun mit der „0“ verglichen. Wenn dieser Ausdruck/Vergleich (expression) wahr ist, wird das Objekt, in diesem Fall der Hintergrund, angezeigt. Bei diesem Ausdruck erhält also jede gerade Zeile den Hintergrund. Möchte man lieber die ungeraden Zeilen hervorheben, schreibt man einfach eine 1 anstelle der 0 hinter „==“.

[[Datei:JasperReports-Handbuch_iReport-Even_Odd_3.jpg]]

Das Ergebnis bei einer ungeraden Hervorhebung sieht z.B. so aus:

[[Datei:JasperReports-Handbuch_iReport-Even_Odd_4.jpg]]

Ein weiteres Beispiel welches bereits in der Uni Mannheim benutzt wird ist die Ausgabe einer Rechnungslegungsliste. Das Beispiel zeigt nicht nur ein aufwändigeres Layout, sondern auch, wie man gruppierte Tabellen anlegt: Dabei sind die Zeilen der Tabelle im Detail 1 Band, und die Zwischensummen in den Gruppierungs-Bändern. Die Spaltenüberschriften der Tabelle befinden sich im untersten Group-Header-Band. Im Designermodus sieht das ganze folgendermaßen aus:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_3_Uma.jpg]]

Und im Preview:

[[Datei:JasperReports-Handbuch_iReport-Beispiel_3_Uma_Ergebnis_1.jpg]]

[[Datei:JasperReports-Handbuch_iReport-Beispiel_3_Uma_Ergebnis_2.jpg]]


=== Rahmenlinien '''vorausschauend setzen''' ===

Sowohl bei Text- als auch bei Static-Fields findet sich ein eigener Reiter zum setzen von Rahmeneigenschaften. Dort wird der Abstand des Inhaltes zum Rahmen des jeweiligen Feldes definiert, sowie Rahmenlinien gesetzt.

Beim Setzen von Rahmenlinien wird empfohlen, dass bei nebeneinanderliegenden Feldern, welche durch eine Rahmenlinie getrennt werden, jeweils in beiden Feldern Rahmenlinien gesetzt werden und nicht nur in einem der beiden Felder. Denn beim Export in das PDF-Format ist ersichtlich ob nur eines der Felder oder beide Felder Rahmenlinien besitzen. Falls dies also nicht einheitlich umgesetzt wird, erscheinen Rahmenlinien an entsprechenden Stellen dünner beziehungsweise dicker (bei Excel-Dokumenten tritt dieser Effekt nicht auf):

[[Datei:JasperReports-Handbuch_borders2.png]]


== Unterberichte ==

<blockquote>Achtung: In Edustore funktionieren Unterberichte nur, wenn der Dateiname der jrxml-Datei mit "_xmlsource.jrxml" endet. Dadurch wird dem Servlet mitgeteilt, dass die Datenquelle für den Bericht ein XML-Datenstrom ist. Dabei ist mit Performanceeinbußen zu rechnen. 
Außerdem muss beim Berichtsdesign die gleiche JasperReports Version genutzt werden wie im Server.
</blockquote>
Im folgenden eine Anleitung zur Erstellung eines Unterberichts:


=== Konfiguration des Hauptberichts ===

Erzeugen Sie für den Unterbericht mit Hilfe des [[#2.1.3.Template erzeugen|outline|Template]][[#2.1.3.Template erzeugen|outline|-Generators]] in Edustore einen leeren Bericht, und speichern Sie diesen am besten im gleichen Verzeichnis wie den Hauptbericht.

Ziehen Sie dann das Subreport-Werkzeug in den Entwurfsbereich:

Ggf.

[[Datei:JasperReports-Handbuch_subreport0_tool.png]]

Es startet der Subreport-Assistent. Hier geben Sie zunächst den Dateinamen oben an:

[[Datei:JasperReports-Handbuch_subreport1_wizard1.png]]

Im nächsten Schritt geben Sie eine Datenbank-Verbindung an. Hier wählen Sie "Don't use any connection...":

[[Datei:JasperReports-Handbuch_subreport1_wizard2.png]]

Im nächsten Schritt werden Parameter angezeigt, zu diesem Zeitpunkt gibt es aber noch keine.

[[Datei:JasperReports-Handbuch_subreport1_wizard3.png]]

Klicken Sie einfach auf "Weiter". Sie werden dann aufgefordert, einen Dateipfad für den Unterbericht zu vergeben. IReport legt diesen standardmäßig in das gleiche Verzeichnis wie den Hauptbericht. Für Edustore sollten Sie dies auch tun.

Bitte beachten Sie dass Sie beim Unterbericht nicht die *.jrxml-Datei verlinken, sondern die *.jasper-Datei, d.h. den kompilierten Report.

[[Datei:JasperReports-Handbuch_subreport1_wizard4.png]]

Danach sehen Sie einen Platzhalter für den Unterbericht im Entwurfsbereich. Beachten Sie bitte daß die Größe des Platzhalters unwichtig ist: die Ausdehnung des Unterberichts wird im Unterbericht definiert. Der Platzhalter ist lediglich wichtig, um die linke obere Ecke des Unterberichts festzulegen. 
Rechts neben dem Platzhalter sehen Sie die Eigenschaften des Unterberichts:

[[Datei:JasperReports-Handbuch_subreport2_params_none.png]]

Ein Unterbericht arbeitet meist mit Übergabe von Parametern, z.B. will man vom Hauptbericht den Inhalts des Feldes "Kostenstelle" an den Unterbericht übergeben. Dies müssen wir in den Eigenschaften des Unterberichts "deklarieren". In der Zeile "Parameters" steht nach Bedienung des Assistenten noch kein Wert. Für die Datenquelle XML gibt es außerdem einen Parameter XML_DATA_DOCUMENT, der immer übergeben werden muss: Die XML-Datenquelle des Hauptberichts. Hier eine Übersicht, welche Parameter übergeben werden:

[[Datei:JasperReports-Handbuch_subreport10_parameters.png]]

Die Zeilen mit Großschreibung sind die vorgegebenen Werte, der Parameter "Kst" speist sich aus dem JR-Feld "Kostenstelle". Das Beispiel zeigt, daß der Name für den Parameter beliebig ist.

'''Hinweis für Unterberichte mit Dezimalzahlen''': Wenn der Unterbericht mit Zahlen mit Nachkommastellen arbeitet, und Sie in JasperReports testen, dann müssen Sie noch die [[#3.1.2.Datenquelle erzeugen|outline|Parameter]] XML_LOCALE und XML_NUMBER_PATTERN wie folgt übergeben:

[[Datei:JasperReports-Handbuch_subreport2_params_number.png]]


=== Unterbericht mit Header und Footer vom Hauptbericht ===

Wenn der Unterbericht in einem normalen Gruppen- oder Detail-Band liegt, wird der Header und Footer vom Hauptbericht automatisch mitbenutzt. In vielen Fällen möchte man aber den Unterbericht nur ein mal ausgeben und legt ihn daher in das Summery-Band. Hier wird Standardmäßig der Header und Footer nicht ausgegeben oder wiederholt. Möchte man aber z.B. die Seitenzahl die im Footer liegt weiterhin angezeigt bekommen, gibt es eine Eigenschaft vom Hauptbericht, die man nur aktivieren braucht. Diese Eingenschaft nennt sich: Summary with Page Header and Footer.

Also einfach auf den Hauptbericht auswählen und in Eigenschaften diesen Punkt aktivieren.

[[Datei:JasperReports-Handbuch_subreport_header_footer.png]]


=== Konfiguration des Unterberichts ===

Nun können wir den Unterbericht öffnen, indem wir über dem Platzhalter die rechte Maustaste betätigen und "Open Subreport" wählen.

[[Datei:JasperReports-Handbuch_subreport3_open.png]]

Es erscheint ein neues Fenster mit einem leeren Entwurfsbereich. Sie könnten nun loslegen und im Detailbereich verschiedene Elemente gestaltet. Aber man muss bedenken daß ein Unterbericht für jeden Datensatz im Hauptbericht ausgeführt und eingebettet wird. Daher wird man vermutlich in den meisten Fällen im Unterbericht auf einen Filter zurückgreifen. Hier kommt dann wieder der oben genannte Parameter, z.B. "Kst" ins Spiel: Als ersten deklarieren wir den Parameter im Unterbericht, indem wir Links bei den Parametern die rechte Maustaste drücken, und "Hinzufügen..." wählen:

[[Datei:JasperReports-Handbuch_subreport4_param.png]]

Standardmäßig nennt IReport den Parameter "parameter1". Rechts können wir in den Eigenschaften des Parameters den Namen ändern, und "Use as a prompt" abwählen:

[[Datei:JasperReports-Handbuch_subreport4_param2.png]]

Weitere Änderungen sind nicht notwendig.

Wir ergänzen nun die "Report Query" [[Datei:JasperReports-Handbuch_report_query.png]] des Unterberichts von

''/ergebnisse/ergebnis/ergebniselement/sqlerg/row''

um einen Filter, der mit der Abfragesprache XPATH formuliert wird. Im obigen Beispiel würden wir jetzt nur die Zeilen der Datenquelle auswählen, wo die Nummer der Kostenstelle mit der des Hauptberichts übereinstimmt. Wir erinnern uns: letztere steht im Parameter "Kst". Anhand der vorhandenen Report Query können wir sehen, dass die Kostenstelle in den Spalten ("col") mit der id=5 steht. Der Ausdruck wird also um den Filter "''[col[@id="5"]/wert='''''$P{Kst}']''" ergänzt:

[[Datei:JasperReports-Handbuch_subreport4_query.png]]

Nun ändern wir im Entwurfsbereich des Unterberichts das Layout: für das aktuelle Beispiel wollen wir im Unterbericht eine Summe der Beträge für jede Kostenstelle ausgeben. Dazu müssen wir zunächst eine Gruppierung nach Kostenstelle hinzufügen:

[[Datei:JasperReports-Handbuch_subreport5_group1.png]]

Im Gruppierungsassistenten wählen wir das Feld "Kostenstelle" als Gruppierungsmerkmal, und im nächsten Schritt sagen wir, daß ein Gruppenkopf hinzugefügt werden soll:

[[Datei:JasperReports-Handbuch_subreport5_group2.png]]

Danach ist die Gruppierung als Band verfügbar:

[[Datei:JasperReports-Handbuch_subreport5_group3.png]]

In die Gruppierung ziehen wir dann das Feld "Summe":

[[Datei:JasperReports-Handbuch_subreport5_group4.png]]

Beim "Loslassen" des Feldes werden wir gefragt, ob wir eine Aggregatfunktion nutzen wollen; wir wählen hier die Summierung:

[[Datei:JasperReports-Handbuch_subreport5_group5.png]]

Danach ist das Feld verfügbar. Wir setzen noch das Label "Summe:" davor.

[[Datei:JasperReports-Handbuch_subreport5_group6.png]]

Den Detailbereich brauchen wir eigentlich nicht, wir können den ganz schmal machen. Danach speichern wir den Unterbericht, und gehen wieder zum Hauptbericht. Hier setzen wir den Unterbericht direkt unter das Feld "Kostenstelle":

[[Datei:JasperReports-Handbuch_subreport15_align.png]]

Danach können wir den Bericht mit der jew. Datenquelle ausführen. Das Ergebnis läßt je nach Datenmenge ein bisschen auf sich warten:

[[Datei:JasperReports-Handbuch_subreport20_erg.png]]


=== Einhängen des Berichts in Edustore ===

Damit der Bericht auch im Server nutzbar ist, muss noch folgendes eingestellt werden:

* Der Server sollte ausreichend RAM haben (Variable CATALINA_OPTS), weil hier XML als Datenquelle verarbeitet wird.
* Im Hauptbericht gibt es einen neuen Parameter SUBREPORT_DIR. Setzen Sie hier den Defaultwert ("Default value Expression" auf den Pfad, in dem die Dateien liegen (z.B. "/home/superx/webserver/tomcat/webapps/superx/WEB-INF/reports/").
* Kopieren Sie die .jasper Datei des Unterberichts in dieses Verzeichnis.
* Bei Nutzung von Versionskontrollsystemen haben Sie die *.jasper-Dateien vermutlich ignoriert (gitignore / svnignore). Sie müssen die Dateien daher mit "-f" adden / committen.

<blockquote>Vorsicht beim Einsatz von JasperSoft Studio: Die Anwendung erzeugt bei der Einzelbearbeitung eines Unterberichts nicht automatisch eine entsprechende .jasper-Datei beim Previewen des Hauptberichts (iReport machte das). Man muss also in Jaspersoft Studio im Bearbeitungsfenster oben immer "Compile Report" anklicken, um eine neue .jasper Datei zu erzeugen.
</blockquote>

== Kreuztabellen ==


=== Bedienung des Assistenten für Kreuztabellen ===

Für die Erstellung von Kreuztabellen gibt es einen eigenen Assistenten. Vorab sollte man aber zunächst ein "Summary"-Band erzeugen. Im folgenden Beispiel haben wir alle anderen Gruppierungen und Detail-Bands entfernt:

[[Datei:JasperReports-Handbuch_designer_crosstab1.png]]

Dann ziehen wir das Crosstab-Element in den Summary Band. Es erscheint der Assistent. Als Datenquelle nutzen wir die Abfrage des Berichts.

[[Datei:JasperReports-Handbuch_designer_crosstab2.png]]

Als nächsten definieren wir die Zeilendimension des Berichts:

[[Datei:JasperReports-Handbuch_designer_crosstab3.png]]

Wir wählen z.B. die Abschlüsse. Danach definieren wir die Spalten-Dimension:

[[Datei:JasperReports-Handbuch_designer_crosstab4.png]]

Wir wählen das Merkmal "Geschlecht". Danach definieren wir das Merkmal, das in den Zellen ausgegeben werden soll. Dies ist die Summe der Studierenden:

[[Datei:JasperReports-Handbuch_designer_crosstab5.png]]

Zum Schluß kann man ein Layout festlegen, und Zeilen- und Spaltensummen erzeugen:

[[Datei:JasperReports-Handbuch_designer_crosstab6.png]]

Im Entwurfsbereich erscheint ein neues Fenster mit der Kreuztabelle.

[[Datei:JasperReports-Handbuch_designer_crosstab7.png]]

Hier können wir nun Spaltenbreiten und Überschriften ändern:

[[Datei:JasperReports-Handbuch_designer_crosstab9.png]]

Das Ergebnis sieht wie folgt aus:

[[Datei:JasperReports-Handbuch_designer_crosstab8.png]]


=== Nachbearbeitung des Kreuztabellen-Assistenten ===

Der Assistent liefert nur einfache Kreuztabellen, ggf. wollen Sie diese im Nachhinein anpassen. Sie können z.B. mehr als zweistufige Hierarchien in Kreuztabellen einrichten, indem Sie im Report Inspector manuell neue Merkmale anlegen.

[[Datei:JasperReports-Handbuch_crosstab_new_row.png]]

Auch bei "Measures" können Sie neue "abhängige Variablen" anlegen, z.B. wenn Sie in einer Tabelle mit den Zeilen "Ausgaben" und "Einnahmen" die Ausgaben mit negativem Vorzeichen versehen wollen und dann saldieren wollen: Sie würden ein neues "Measure" anlegen, mit der Calculation="Sum", Typ "java.lang.Float", und der folgenden Expression bekommen alle Ausgaben ein negat. Vorzeichen:

($F{Kostenart}=="Ausgaben")?-$F{Betrag}:$F{Betrag}

Das neue Measure können Sie dann in die Zeilen- oder Spaltensummen ziehen.


=== Kreuztabellen im Gruppenfuß ===

Kreuztabellen lassen sich nicht nur im Summary Band nutzen, sondern auch in Gruppenfuß/Gruppenkopf-Bändern. Wenn Sie die Kreuztabelle z.B. in einen Groupfooter legen, müssen Sie den "Reset type“ der Gruppe anpassen. Das machen Sie indem Sie ein rechts klick auf die Kreuztabelle machen und dann auf "Crosstab data" klicken. Dort stellen Sie den "Reset type" auf "Group" und die "Reset group" auf die Gruppe in der die Kreuztabelle gelegt wurde. Wenn Sie das nicht machen funktioniert der Report nicht!


=== Kreuztabellen mit virtuellen Dimensionen ===

Sie können auch virtuelle Dimensionen in Kreuztabellen nutzen, indem Sie ähnlich wie bei der [[#2.2.4.Gruppierung ohne eigenes Band|outline|Gruppierung ohne eigenes Band]] mit Variablen arbeiten.

Um z.B. alle Studienfächer im Feld "1. Fach" auszugeben, und nur die Fächer Mathematik, Physik und Biologie zu einem Fach "Naturwissenschaften" zusammenzufassen, legen Sie eine neue Variable "fachgruppe" an, mit der Expression:

[[Datei:JasperReports-Handbuch_gruppierung_virtuell.png]]

In der Kreuztabelle können Sie nun z.B. in den Zeilen die Variable "fachgruppe" auswählen, und erhalten eine Tabelle mit der "künstlichen" Zeile "Naturwissenschaften":

[[Datei:JasperReports-Handbuch_gruppierung_virtuell2.png]]


=== Sortierung in Kreuztabellen ===

Zeilen- oder Spaltendimensionen werden in Kreuztabellen immer alphabetisch sortiert, egal wie die Sortierung in der Datenquelle ist. Das ist in der Regel kein Problem, aber wenn z.B. eine Zeilendimension anders sortiert werden soll, geht das nicht ohne weiteres. Hier ein Problembeispiel:

[[Datei:JasperReports-Handbuch_kreuztab_sortierung_falsch.png]]

Das Balkendiagramm übernimmt die Sortierung nach dem Schlüssel der Gehaltsgruppe aus der Datenquelle. In der Kreuztabelle wird die Zeilendimension "Bezeichnung der Gehaltsgruppe" angezeigt, und diese sortiert alphabetisch, was an dieser Stelle aber unsinnig ist: Der Eintrag "Kein Einkommen" sollte ganz oben stehen.

Wir schauen uns zunächst die Definition der Kreuztabelle an:

[[Datei:JasperReports-Handbuch_kreuztab_sortierung_richtig1.png]]

Die Zeilendimension sortiert aufsteigend nach Bezeichnungstext. Man kann auch keine alternative Expression als Sortierkriterium angeben. Wir müssen also einen Trick anwenden: wir nehmen den Sortierschlüssel mit in die "Bucket Expression" der Zeilendimension auf, und setzen ihn als Präfix davor:

[[Datei:JasperReports-Handbuch_kreuztab_sortierung_richtig2.png]]

Danach ist die Sortierung richtig:

[[Datei:JasperReports-Handbuch_kreuztab_sortierung_richtig3.png]]

Aber optisch ist das natürlich unschön, der Sortierschlüssel sollte am besten gar nicht angezeigt werden. Wir lösen das, indem wir den Anzeigetext wiederum so abwandeln, dass der erste Buchstabe nicht sichtbar ist. Java bietet dazu die Funktion "substring()":

[[Datei:JasperReports-Handbuch_kreuztab_sortierung_richtig4.png]]

Und siehe da: die Sortierung und Anzeige ist perfekt:

[[Datei:JasperReports-Handbuch_kreuztab_sortierung_richtig5.png]]

Dies ist nur ein Beispiel, wie man mit Hilfe von Java Expressions die Anzeige von Kreuztabellen variieren kann.


=== Parameter für Kreuztabellen ===

In Kreuztabellen hat man keinen direkten Zugriff auf die Variablen und Felder des Hauptberichts. Man kann die Werte aber als Parameter übergeben. Dazu gehen Sie wie folgt vor:

Sie machen den Parameter im Crosstab-Element bekannt, hier z.B. der Parameter "RSZ" für Regelstudienzeit):

[[Datei:JasperReports-Handbuch_crosstab_param1.png]]

Danach übergeben Sie den Parameter im Hauptbericht. Mit Rechtsklick auf das Cosstab Element können Sie eine Parameters-Map Expression hinterlegen, das ist einfach eine Zuweisung von einer oder mehreren Variablen zu jeweils einem Wert in der Groovy-Syntax mit "[Variable:Wert,...]". In dem Beispiel unten weisen wir dem Parameter "RSZ" den Wert des Feldes "RSZ" zu:

[[Datei:JasperReports-Handbuch_crosstab_param2.png]]

Danach können wir den Parameter in der Kreuztabelle nutzen, z.B. um in einer Spaltenüberschrift nur dann eine Zahl mit Soll-Kreditpunkten anzuzeigen, wenn die Fachsemester innerhalb der Regelstudienzeit liegen.

[[Datei:JasperReports-Handbuch_crosstab_param3.png]]

Und hier das Ergebnis für einen Studiengang mit 6 Semestern Regelstudienzeit:

[[Datei:JasperReports-Handbuch_crosstab_param5.png]]


=== Manuelle Kreuztabelle ===

Wenn die gewünschte Konfiguration/Einstellungen in der Kreuztabelle nicht möglich ist, kann eine Kreuztabelle mit Einschränkungen auch selber erstellt werden. Im Beispiel mit Semestern, muss vorher abgeschätzt werden wie viele Semester vorraussichtlich in den Spalten vorkommen werden. Für jedes Semester (z.B. für 10 Semester) wird dann eine Variable angelegt. Die erste bekommt das höchste Semester (wie im Screenshot zu sehen).

[[Datei:JasperReports-Handbuch_kreuztabelle_manuell_1.jpg]]

Das zweite Semester wir dann das höchste welches aber unterhalb von dem ersten liegen soll, usw.

[[Datei:JasperReports-Handbuch_kreuztabelle_manuell_2.jpg]]

Diese Semester können nun als Spalten verwendet werden mit der Option „blank when null“.


=== Layout von Kreuztabellen bearbeiten ===

Dieser Abschnitt befasst sich mit Themen zur Layoutanpassung.


==== Total einer ‚Row Group‘ entfernen ====

Wenn eine neue ‚Row Group‘ angelegt wird, wird automatisch ein dazugehöriges Total-Feld erzeugt und mit eingefügt:

[[Datei:JasperReports-Handbuch_Eingebettet_001.png|642x367px]]

Das ist in diesem Falle nicht erwünscht. Um dieses Feld zu entfernen, wird in den Properties der ‚Row Group‘ die ‚Total Position‘ = ‚none’ gesetzt:

[[Datei:JasperReports-Handbuch_Eingebettet_002.png|642x263px]]


==== Header von ‚Row Groups‘ für jede Zeile wiederholen ====

Im folgenden Screenshot ist eine Kreuztabelle dargestellt, bei welcher die Header der ‚Row Groups‘ nur einmal dargestellt werden:

[[Datei:JasperReports-Handbuch_Eingebettet_003.png|434x315px]]

Zwar ließe sich das Feld noch, so dass es bis zum nächsten ‚Row Header‘ reicht, aber in diesem Beispiel ist erwünscht, dass sich der Header für jede Zeile wiederholt:

[[Datei:JasperReports-Handbuch_Eingebettet_004.png|530x420px]]

Dazu wird die Funktion ‚Merge Header Cells‘ in den Properties der ‚Row Group‘ deaktiviert. Es kann sein, dass die Funktion einmal aktiviert und dann wieder deaktiviert werden muss, damit sie als deaktiviert erkannt wird.

[[Datei:JasperReports-Handbuch_Eingebettet_005.png|642x275px]]

Damit der Text in der ersten Spalte nicht abgeschnitten wird, wurde ‚Stretch with Overflow‘ in den Text-Field-Properties ausgewählt. Dadurch ist eine Lücke bei den anderen Spalten entstanden.

[[Datei:JasperReports-Handbuch_Eingebettet_006.png|509x404px]]

Um diese Lücke zu schließen wird der ‚Stretch Type‘ in allen folgend eingerahmten Textfeldern auf ‚Relative To Band Height (deprecated)‘ gesetzt:

[[Datei:JasperReports-Handbuch_Eingebettet_007.png|642x322px]]


==== ‚Static Field‘ und ‚Text Field‘ frei gestalten/bewegen ====

Im Default sind ‚Static Field‘ und ‚Text Field‘ in einer Kreuztabelle nicht frei positionierbar/gestaltbar. Um das zu ändern, wird im jeweiligen Bereich das Layout auf ‚Free Layout‘ eingestellt.

[[Datei:JasperReports-Handbuch_Eingebettet_008.png|642x279px]]


==== Reihenfolge der ‚Row Groups‘ ändern ====

Die Reihenfolge der ‚Row Groups‘ muss nachträglich im ‚Outline‘-Bereich geändert werden. Dies erfolgt per Drag and Drop im rot markierten Bereich:

[[Datei:JasperReports-Handbuch_Eingebettet_009.png|642x437px]]

Die Textfelder im Design-Bereich zu verschieben, reicht nicht aus, denn die ‚Row Group‘ selbst bleibt wo sie ist und dann würde nur das Textfeld in eine andere Row Group verschoben. Im folgenden Negativbeispiel wurden nachträglich im Design-Bereich die Textfelder Intervall und Datenherkunft vertauscht. Dadurch sind sie in der jeweils falschen ‚Row Group‘ gelandet:

[[Datei:JasperReports-Handbuch_Eingebettet_010.png|642x387px]]


== Diagramme ==

Um einen Bericht ansprechend zu gestalten dürfen Diagramme wie Torten- oder Balkendiagramme nicht fehlen. Diese in einen Bericht einzubringen ist auch nicht schwer.

<blockquote>Vorab sei aber darauf hingewiesen: Grafiken in JasperReports arbeiten nicht analog zu Kreuztabellen, in denen Daten nach Zeilen- oder Spaltenmerkmalen automatisch gruppiert und summiert werden. Für Grafiken sollten Sie gewährleisten, dass die Datenbasis für die Grafik '''bereits gruppiert und summiert''' sind, Sie können also keine Einzeldaten für Grafiken verwenden. Bei Datenblatt-Berichten in Edustore ist dies gewährleistet, wenn Sie im Feld "Felder" nur die Felder selektieren, nach denen in der Grafik gruppiert werden soll.
</blockquote>

=== Einfache Diagramme ===

Nehmen wir an wir haben eine Tabelle, die die Studierendenzahl mehrerer Semester nach Geschlecht aufführt. Hier ein Screenshot der Datengrundlage:

[[Datei:JasperReports-Handbuch_jaspersoft_design_query3.png]]

Die Tabelle enthält die Merkmale Geschlecht, Semester und Summe. Daraus erzeugen wir in Jaspersoft Studio (und weiter unten in iReport) ein Balkendiagramm.


==== Einfache Diagramme in JasperSoft Studio ====

Zunächst definieren wir die Sortierung der Daten. Im "Dataset and Query Dialog" sind die Felder der Datenquelle aufgeführt. Unten finden Sie den Reiter "Sorting":

[[Datei:JasperReports-Handbuch_jaspersoft_design_query2.png]]

Damit die Grafik richtig funktioniert müssen wir nach beiden Merkmalen (Semester und Geschlecht) sortieren. Das Semester sollte nicht alphabetisch nach Namen sortiert sein, sondern nach dem Zahlenschlüssel. Sonst ständen alle Wintersemester untereinander, und davor alle Sommersemester.

Dann ziehen wir aus der Palette das Chart Element in das Summary Band. Es startet automatisch ein "Chart Wizward". Hier wählen wir "Stacked Bar" als Grafiktypen:

[[Datei:JasperReports-Handbuch_jaspersoft_design_chart_wizard1.png]]

Nun müssen wir ihm sagen welches Feld die Y-Achse darstellt (hier "Summe"), und welches die X-Achse (hier "Semester der Belegung"). Das Merkmal zur Unterscheidung der Balkenfarben ("Series") ist das Geschlecht:

[[Datei:JasperReports-Handbuch_jaspersoft_design_chart_wizard2.png]]

Danach klicken wir auf "Finish", und die Grafik wird als Platzhalter im Summary Band eingefügt. Dort definieren wir noch die Breite der Grafik:

[[Datei:JasperReports-Handbuch_jaspersoft_design_chart1.png]]

Damit ist der Entwurf fertiggestellt. So sieht die Grafik aus:

[[Datei:JasperReports-Handbuch_jaspersoft_design_chart_wizard3.png]]

Es ist etwas ungünstig dass die Labels der X-Achse nicht ganz lesbar sind. Wir lösen dies mit Rotation der Labels um 45 Grad:

[[Datei:JasperReports-Handbuch_jaspersoft_design_chart_wizard4.png]]

So sieht es besser aus:

[[Datei:JasperReports-Handbuch_jaspersoft_design_chart_wizard5.png]]

Das Beispiel lädt zur weiteren Verfeinerung an.


==== Einfache Diagramme in iReport ====

Hier die Ansicht in iReports "Refresh Preview Data":

[[Datei:JasperReports-Handbuch_designer_chart2.png]]

Die Spalten der Tabelle sind selbsterklärend. Nun ziehen wir aus dem "Report Elements" die "Chart" in das Band "Summary".

[[Datei:JasperReports-Handbuch_grafik_chart_in_summary_ziehen.png]]

Dabei öffnet sich ein Fenster in dem Sie sich die Art der Grafik auswählen können. In diesem Beispiel wählen wir "Stacked Bar 3D".

[[Datei:JasperReports-Handbuch_grafik_chart_auswaehlen.png]]

Nach dem Klick auf "OK", geht es weiter mit den Inhalten der Grafik.

Als Dataset gibt es hier nur eine Auswahl.

[[Datei:JasperReports-Handbuch_grafik_dataset_auswaehlen.png]]

Daher akzeptieren wir dies mit einem Klick auf "Weiter".

Die "Series" sind die verschiedenen Unterteilungen eines Balkens. Die "Series" sind die verschiedenen Unterteilungen eines Balkens. Wir wählen hier das Merkmal "Geschlecht":

[[Datei:JasperReports-Handbuch_designer_chart3.png]].

Bei der X-Achse (in JasperReports heißt das "Category Axis") nehmen wie das Merkmal Semester, und bei der "Value expression" die Summe.

[[Datei:JasperReports-Handbuch_designer_chart4.png]]

Damit ist die Definition beendet. Wir können dann in den Eigenschaften der Grafik noch eine "Title Expression" festlegen, z.B. "Studierende nach Semester und Geschlecht". In der Vorschau sieht die Grafik so aus:

[[Datei:JasperReports-Handbuch_designer_chart5.png]]

Die Wintersemester werden noch nicht abgedruckt, dazu ändern wie die "Label rotation" auf 30°. Dies lässt die Schrift unter den Balken rotieren, damit längere Schriftzüge möglich sind.

[[Datei:JasperReports-Handbuch_designer_chart6.png]]

Wichtig für die Grafik war die Sortierung in der Datenquelle nach "dim_semester.quell_id". Mit "Series Colors" kann man die Farbe der Balken ändern etc.

<blockquote>Wenn sie jeden Balken bzw. Teil des Balkens zusätzlich mit den Werten ausgeben wollen, müssen sie in den Chart-Eigenschaften unter den "Bar*Properties" das Ankreuzfeld "Show labels" ankreuzen. Wenn es bereits angekreuzt ist, sollten Sie das Kreuz einmal entfernen und wieder setzen (Bug in iReport seit Version 4.x)
</blockquote>

=== Diagramme nach Tabelle ausgeben ===

Üblicherweise ähnelt ein Diagramm in JasperReports einer Kreuztabelle. Wenn nun ein Diagramm nach Vorgabe einer Tabelle ausgegeben werden soll, muss ein wenig getrickst werden.

Erläuterung:

In der Series expression werden die Zeilen angegeben.

In der Category expression werden die Spalten angegeben.

In der Value expression wird der Wert angegeben.

Um ein Diagramm nun zu erstellen muss pro Series + Category eine Categorie series angelegt werden und das entsprechende Feld angegeben werden.


=== Diagramme mit berechneten Werten ===

Wenn die einem Diagramm zugrunde liegende Tabelle noch Berechnungen erfordert, muss man mit Variablen arbeiten. Als Beispiel wird hier die Maske "Studierende und Studienanfänger (Zeitreihe)" benutzt. Das Ergebnis wird eine Tabelle mit Balkendiagramm der "Studierende und Studienanfänger im 1. Fachsemester (Zeitreihe)" sein.

Ein bereits fertiges Datenblatt könnte folgendermaßen aussehen:

[[Datei:JasperReports-Handbuch_grafik_datenblatt_ohne_grafik.jpg]]

Hier fehlt jetzt die Grafik, die in dem noch leeren Band "Summary" eingefügt werden soll. Wenn das Band noch nicht eingefügt wurde, einfach mit Rechtsklick auf Summary (im "Report Inspector") und dann auf "Add Band" um es anzuzeigen.

[[Datei:JasperReports-Handbuch_grafik_how_to_add_summary.png]]

Nun ziehen wir aus dem "Report Elements" die "Chart" in das Band "Summary".

[[Datei:JasperReports-Handbuch_grafik_chart_in_summary_ziehen.png]]

Dabei öffnet sich ein Fenster in dem Sie sich die Art der Grafik auswählen können. In diesem Beispiel wählen wir "Stacked Bar 3D".

[[Datei:JasperReports-Handbuch_grafik_chart_auswaehlen.png]]

Nach dem Klick auf "OK", geht es weiter mit den Inhalten der Grafik.

Als Dataset gibt es hier nur eine Auswahl.

[[Datei:JasperReports-Handbuch_grafik_dataset_auswaehlen.png]]

Daher akzeptieren wir dies mit einem Klick auf "Weiter".

Die "Series" sind die verschiedenen Unterteilungen eines Balkens. Da es in diesem Beispiel dafür keine Variable gibt, wird später noch per Hand eine Weitere hinzugefügt. Wenn es bei Ihnen möglich ist, klicken Sie rechts neben dem Feld auf den Button und fügen dort eine Variable ein. In diesem Beispiel wird als fester String "Frauen im 1. FS" eingegeben.

[[Datei:JasperReports-Handbuch_grafik_series_auswaehlen.png]]

Und dann wieder auf "Weiter".

Auf der X-Achse soll in diesem Beispiel die Semester erscheinen und auf der Y-Achse die Anzahl der Weiblichen Studierenden im 1. Fachsemester. Um dies zu erhalten wählt man als "category expression" die Variable "Semester" aus.

[[Datei:JasperReports-Handbuch_grafik_category_auswaehlen1.png]]

Dies geschieht, indem man auf den Button rechts neben dem Feld klickt,

[[Datei:JasperReports-Handbuch_grafik_category_auswaehlen2.png]]

dann doppelt auf das Feld "Semester" klickt und dann auf "Apply".

In den meisten Fällen werden hier Felder benutzt. Wenn Sie jedoch z.B. eine Variable benutzen wollen, müssen Sie nach dem Klick rechts auf den Button in dem neuen Fenster links unten z.B. auf "Variables" oder "Parameter" klicken. Dabei ändert sich der Inhalt von dem mittleren Feld.

[[Datei:JasperReports-Handbuch_grafik_category_auswaehlen3.png]]

Hier können Sie nun auch eine andere Auswahl treffen.

Das selbe gilt auch für "value expression". Der Unterschied ist hierbei, die "category expression" ist die Bezeichnung und in "value expression" dürfen nur Zahlen vorkommen, welche von JasperReports addiert werden können.

[[Datei:JasperReports-Handbuch_grafik_value_auswaehlen1.png]]

Hier wählen wir nun z.B. das Feld "1. FS Frauen" aus.

[[Datei:JasperReports-Handbuch_grafik_value_auswaehlen2.png]]

Nun noch abschließend auf Beenden drücken und wir erhalten das erste Ergebnis. Über "Preview" wird nun das Diagramm mit den Frauen aus dem 1. Fachsemester über die Semester angezeigt.

[[Datei:JasperReports-Handbuch_grafik_erstes_ergebnis.png]]

Um nun die männlichen Studenten aus dem 1. FS noch hinzuzufügen oder Änderungen an der gerade getroffenen Auswahl vorzunehmen klickt man mit der rechten Maustaste auf die Chart und dann auf "Chart Data". In dem Reiter "Details" kann man nun die eben angelegte Category bearbeiten/entfernen oder auch eine neue anlegen.

[[Datei:JasperReports-Handbuch_grafik_chart_details.png]]

Hier wollen wir jetzt noch die männlichen Studierende aus dem 1. FS noch Hinzufügen. Also klickt man auf "Hinzufügen.

[[Datei:JasperReports-Handbuch_grafik_chart_m_std_1fs_hinz.png]]

Die Eingabe funktioniert hier genau wie in dem Assistenten bei der Erstellung einer neuen Chart. Nur taucht jetzt das Problem auf, dass es kein Feld mit den Männlichen Studierenden gibt, sondern nur gesamt. Die Lösung ist aber ganz einfach. Zunächst geht man wieder in den "Expression editor" der "Value expression" und wählt das Feld "1. FS gesamt" aus, setzt dahinter ein Minuszeichen und danach wählt man noch das Feld "1. FS Frauen" aus. Jasper berechnet dann jeweils das Ergebnis und benutzt dieses als Value.

[[Datei:JasperReports-Handbuch_grafik_chart_m_std_1fs_hinz_1.png]]

Nun erhalten wir als Ergebnis folgende Tabelle:

[[Datei:JasperReports-Handbuch_grafik_zweites_ergebnis.png]]

Es gibt noch viele Änderungsmöglichkeiten unter Einstellungen wie z.B. "Label rotation" lässt die Schrift unter den Balken rotieren, damit längere Schriftzüge möglich sind und "Series Colors" um die Farbe der Balken zu ändern.

[[Datei:JasperReports-Handbuch_grafik_zweites_ergebnis1.png]]


=== Chart Customizer ===

Mit JasperSoft Studio können die über sog. "Chart Customizer" Details bzgl. des Layouts vor Diagrammen steuern. Im folgenden ein Beispiel:

Wir haben ein einfaches Balkendiagramm, in dem wir eine (automatisch) ermittelte Y-Achse mit Werten von 0-15 haben:

[[Datei:JasperReports-Handbuch_jr_chart_customizer_range1.png]]

Nun wollen wir den Bereich auf 12 (in 2er-Schritten ändern). Man könnte dies ganz leicht über die Eigenschaften ändern:

[[Datei:JasperReports-Handbuch_jr_chart_customizer_range2a.png]]

Hier kann man aber nicht die Schrittweite ändern. Wir legen dazu einen Chart Customizer vom Typ "Value Axis Range and Tick" an:

[[Datei:JasperReports-Handbuch_jr_chart_customizer_range2.png]]

und damit sieht das Diagramm so aus:

[[Datei:JasperReports-Handbuch_jr_chart_customizer_range3.png]]

Die Y-Achse zählt nun in 2er Schritten von 0 bis 12.

<blockquote>Noch ein Hinweis: Bei Y-Achsen mit kleinen Wertebereichen kann es vorkommen, dass JR die Y-Achse automatisch mit Intervallen mit Nachkommastellen versieht, also z.B. 1 - 1,5 - 2 - 2,5 etc. Bei manchen Maßen macht die Nachkommastelle keinen Sinn (z.B. wenn Studierende gezählt werden). Um das zu ändern gehen Sie in der Eigenschaften der Y-Achse (Chart → Value axis) und setzen bei der Eigenschaft "Value axis tick label mask" den Wert "#" (Pattern für ganzzahlig) ein. Damit wird nur noch ganzahlig hochgezählt.
</blockquote>

=== Balken Labels ===

In Balkendiagrammen können die exakten Zahlen nicht genau ermittelt werden. Aus diesem Grund wird oft gewünscht, die Zahlen noch mal schriftlich darzustellen.

[[Datei:JasperReports-Handbuch_balken_labels_1.png]]

Um die Zahlen anzeigen zu lassen muss einfach in den Chart Properties unter Advanced „Common Chart Properties → Plot → Show Labels“ auf true gesetzt werden.


== Booklets ==

Ab JR 6.2 oder höher (d.h. SuperX-Kernmodul 4.8 oder HISinOne-BI 2018.12) gibt es die Möglichkeit, Berichts-"Bücher" mit Deckblatt, Inhaltsverzeichnis und Schlußseite zu erstellen. Die Erstellung ist übersichtlicher als eine Kombination aus Haupt- und Unterbericht, und bietet beim Seitenlayout mehr Optionen, z.B. kann man in einem Booklet Hoch- und Querformat kombinieren.

Englische Anleitungen siehe

https://community.jaspersoft.com/documentation/tibco-jaspersoft-studio-user-guide/v60/report-books

Wg. der Version ist diese Möglichkeit in iReport nicht mehr verfügbar, Sie müssen JasperSoft Studio nutzen. Wenn Sie dort mit File -> New einen neuen Report erzeugen, können Sie bei Report type den Wert "Book report" wählen. Der Assistent fragt Sie dann, ob Sie Deckblatt, Inhaltsverzeichnis und die Schlußseite benötigen, kreuzen Sie die jew. Position an. Sie erhalten danach ein Entwurfsfenster mit dem Hauptbericht, der drei Abschnitte enthält: Das Deckblatt und Inhaltsverzeichnis ("Cover and table of contents"), den Buchinhalt ("Content") und die Schlußseite ("Backcover"):

[[Datei:JasperReports-Handbuch_booklet_main1.png]]

Wenn Sie die Datei speichern, werden die jew. Unter-Dateien automatisch mit angelegt, mit dem Zusatz "*_cover.jrxml", "*_toc.jrxml" und "*_backcover.jrxml".


=== Hauptbericht im Booklet ===


==== Aufbau des Hauptberichts ====

Startpunkt beim Booklet ist der Hauptbericht. Dieser hat keine "Bänder" im Sinne einer Ergebnisausgabe, insbesondere gibt es kein Detailband. Trotzdem arbeitet der Hauptbericht mit einer Datenquelle im Sinne eines Detailbandes, hier heißt das Band "Content". Für Makroberichte in SuperX-/BI müssen wir für alle Unterberichte dieselbe XML-Quelle verwenden, d.h. wir müssen im Hauptbericht genau eine Zeile der XML-Quelle filtern. Wir machen das mit XPATH mit dem Ausdruck 

/ergebnisse/ergebnis[@ordnr='0']/ergebniselement/sqlerg/row[@no='0']

Dies liefert die erste Zeile der ersten Tabelle des Makroberichts im Ergebnis.

Klicken Sie also oben auf die Datenquelle des Hauptberichts, und fügen Sie den Filter ein:

[[Datei:JasperReports-Handbuch_booklet_main2.png]]

Die Funktion „Read Fields“ funktioniert in diesem Fall nicht. Die Felder für den Hauptbericht werden manuell in den Sourcecode eingefügt. Dazu erstellen Sie zunächst, wie in [[#4.5.Makroberichte als Datenquelle für JasperReports|outline|Abschnitt 4.5]] beschrieben, ein JR-Template für den Makrobericht. Aus diesem Template kopieren Sie aus dem Sourcecode die Felder und fügen diese im Booklet ein. Fügen Sie alle Felder sowohl im Haupt- als auch in den Unterberichten des Booklets ein.

Im Content Band können Sie dann mit der rechten Maustaste die jew. Unterberichte verlinken. Die Technik ist identisch mit den normalen Haupt/-Unterberichten, nur dass das Seitenlayout nicht vom Hauptbericht zum Unterbericht vererbt wird.

Im Beispiel haben wir einen Unterbericht verlinkt:

[[Datei:JasperReports-Handbuch_booklet_main3.png]]

Im Feld "Component Expression" geben Sie den Unterbericht an. Im Feld "Tab name expression" können Sie den Namen des TABs in Excel definieren. Standardmäßig wird bei einem Booklet beim Export nach Excel also ein Arbeitsblatt mit mehreren Sheets.

Der Unterbericht wird mit den gleichen Parametern aufgerufen wie bei klassischen [[#2.5.1.Konfiguration des Hauptberichts|outline|Unterberichten]]. Der erste Unterbericht bekommt die ordnr 0, der zweite Unterbericht die ordnr 1 usw.:

[[Datei:JasperReports-Handbuch_booklet_main4.png]]


=== Übergabe von Layouts vom Hauptbericht an Unterberichte ===

Generell werden im Booklet keine Layoutvorgaben vom Hauptbericht an den jew. Unterbericht übergeben. Ausnahme: Die Property "net.sf.jasperreports.export.xls.detect.cell.type", die beim Excel Export als Zahl formatierte Zellen auch in Excel als Zahl ausgibt, wird im Hauptbericht gesetzt und dann an die Unterberichte übergeben.

Achtung: Je nach JasperSoft Studio Version kann man diese Property nicht in der graphischen Entwcklungsumgebung setzen, sondern nur im *.jrxml-Quellcode.


=== Booklet Deckblatt ===

Das Deckblatt ist ein normaler JasperReport mit Elementen im Titel-Band. Beachten Sie dass im Unterbericht auch Seitenränder und Seitenformate definiert sein müssen. Sie können auch vom Hauptbericht Parameter übergeben, hier z.B. das Semester:

[[Datei:JasperReports-Handbuch_booklet_cover1.png]]

Im Hauptbericht wiederum wird dieser Parameter dann übergeben, hier z.B. aus der Legende der Maske:

[[Datei:JasperReports-Handbuch_booklet_cover2.png]]


=== Booklet Inhaltsverzeichnis ===

Das Inhaltsverzeichnis ist ein Bericht ohne Datenquelle, und bekommt über die Evaluation Time="Report" die Anweisung, die Inhaltsdokumente nach Lesezeichen (HTML-Anchors) zu durchsuchen.

[[Datei:JasperReports-Handbuch_booklet_toc1a.png]]

Die Datenquelle ist leer, und über die Property

net.sf.jasperreports.bookmarks.data.source.parameter=REPORT_DATA_SOURCE

wird als Datenquelle der Content angegeben.

[[Datei:JasperReports-Handbuch_booklet_toc1b.png]]

Das Berichtsdesign ist vom Assistenten vorgegeben und relativ einfach. Sie können bis zu drei Ebenen für das Inhaltsverzeichnis angeben, jede Ebene benötigt ein eigenes Detailband.

[[Datei:JasperReports-Handbuch_booklet_toc2.png]]

Die Feldnamen im Bericht sollten nicht geändert werden. Sie können aber das Layout anpassen.


=== Booklet erster Detailbericht ===

Der Detailbericht ist ein normaler Unterbericht, d.h. er hat den Parameter "ordnr":

[[Datei:JasperReports-Handbuch_booklet_content1.png]]

Die Variable "ordnr" wird dann bei der Datenquelle des Unterberichts ausgewertet:

[[Datei:JasperReports-Handbuch_booklet_content2.png]]

Der Unterbericht soll sicherlich auch Seitenzahlen anzeigen, dazu fügen Sie noch ein "Page footer" Band hinzu, und erzeugen dort ein Textfeld mit dem Inhalt z.B.

"Seite "+$V{MASTER_CURRENT_PAGE}

Das Textfeld muss bei Evaluation time den Wert "Master" haben.

[[Datei:JasperReports-Handbuch_booklet_content3.png]]

Danach wird die Seitenzahl jedes Unterberichts an den Hauptbericht angepaßt.

Für das Inhaltsverzeichnis müssen Sie im jew. Detailbericht Lesezeichen (HTML-Anchors) und jeweils eine Ebene angeben. Wir können z.B. für das Textfeld der Überschrift einen Anker der Ebene 1 festlegen:

[[Datei:JasperReports-Handbuch_booklet_content4.png]]

Danach legen wir für das Gruppenband für das Textfeld mit dem Label der Gruppe (Fakultätsname) einen Anker der Ebene 2:

[[Datei:JasperReports-Handbuch_booklet_content6.png]]


=== Das fertige Booklet ===

So sieht das Booklet im Preview im JasperSoft Studio aus: Zuerst das Deckblatt...

[[Datei:JasperReports-Handbuch_booklet_preview1.png]]

... und dann auf Seite 2 das Inhaltsverzeichnis:

[[Datei:JasperReports-Handbuch_booklet_preview1b.png]]

und dann auf Seite 3 der erste Unterbericht:

[[Datei:JasperReports-Handbuch_booklet_preview2.png]]


== Schriften ==


=== Allgemeines zu Schriften ===

Für den Entwurf von Berichten ist es wichtig, daß die jew. Schriftart auch beim Server-System und beim Client verfügbar sind.

<blockquote>Ein häufiger Fallstrick ist hier: unter Windows wird mit JasperReports entworfen, und dort z.B. die Schriftart "Arial" gewählt. Der Report soll auf dem Server unter Linux laufen, dort gibt es die Schriftart nicht. Resultat: der Bericht ist nicht kompilierbar.
</blockquote>
Bei PDF-Dateien lassen sich Fonts ggf. auch in die Datei einbetten, bei Exportformaten wie OpenOffice oder Word ist dies nicht möglich. Sie sollten daher Schriftarten wählen, die auch beim Client mit größter Wahrscheinlichkeit installiert sind. Die sicherste Wahl ist es, Font-Familien anzugeben, z.B. "Serif".

Im Zweifelsfall installieren Sie die Schriftart auf allen beteiligten Systemen. TrueType Fonts lassen sich in JasperReports importieren und nutzen, sie können sogar in PDF-Dateien standardmäßig eingebettet werden. Im folgenden wird die Schriftart "Liberation Sans" installiert, die man auf [https://fedorahosted.org/liberation-fonts/ https://fe][https://fedorahosted.org/liberation-fonts/ dorahosted.org/liberation-fonts/] herunterladen kann. Entpacken Sie das Download Paket in einem beliebigen Verzeichnis.


=== Schriften in iReport einbinden ===

Achtung: wenn Sie iReport unter Windows nutzen, müssen Sie für die folgenden Schritte iReport als Admin starten:

Im Menü "Extras"->"Optionen" können Sie den Font importieren:

[[Datei:JasperReports-Handbuch_font_import_step1.png]]

Wählen Sie aus der Dateiliste zunächst den "Regular"-Font aus, z.B. die Sans-Serif-Variante. Im nächsten Schritt geben Sie dem Font einen Namen, und Sie wählen die zugehörigen Dateien für Fettdruck etc:

[[Datei:JasperReports-Handbuch_font_import_step2.png]]

Außerdem kreuzen Sie an, daß der Font in die jew. PDF-Datei eingebettet wird. Die nächsten zwei Dialoge (Locales, Font Mappings) lassen wir der Einfachheit halber erstmal weg. Wenn Sie dann OK drücken, ist der Font in iReport installiert. Sie können die Einstellungen jederzeit ändern, indem Sie auf "Edit Font" klicken:

[[Datei:JasperReports-Handbuch_font_import.png]]

Hier die Ansicht, wenn Sie auf "Edit Font" klicken:

[[Datei:JasperReports-Handbuch_font_import1.png]]

Am Ende des Formulars können Sie noch PDF-Exportoptionen wählen, z.B. ob die Schriftart in PDF-Dateien eingebunden werden soll. Achtung: beachten Sie lizenzrechtliche Fragen, die wenigsten Fonts sind ohne weiteres kopierbar. Wir empfehlen den Liberation-Font, der steht unter der OpenSource Lizenz GPL.


=== Schriften in '''JasperSoft Studio''' einbinden ===

Unter „Window“ → „Preferences“ können Sie Fonts einbinden:

[[Datei:JasperReports-Handbuch_font_import4.png]]

Nach einem Klick auf „Add“ öffnet sich ein neues Fenster. Dort geben Sie dem Font einen Namen und wählen die zugehörige Datei für den normale Ausführung des Fonts. Es gibt weitere Reiter für Bold, Italic und Bold Italic:

[[Datei:JasperReports-Handbuch_font_import5.png]]

Außerdem kreuzen Sie an, daß der Font in die jew. PDF-Datei eingebettet wird. Die nächsten zwei Dialoge (Locales, Font Mappings) lassen wir der Einfachheit halber erstmal weg. Wenn Sie dann OK drücken, ist der Font in iReport installiert.

Sie können die Einstellungen jederzeit ändern, indem Sie auf "Edit Font" klicken:

[[Datei:JasperReports-Handbuch_font_import6.png]]

Achtung: Beachten Sie lizenzrechtliche Fragen, die wenigsten Fonts sind ohne weiteres kopierbar. Wir empfehlen den Liberation-Font, der steht unter der OpenSource Lizenz GPL.


=== Default-Schriftart in iReport ===

Sie können die Default Schriftart in iReport einstellen:

[[Datei:JasperReports-Handbuch_ireport_default_font.png]]

Stellen Sie den Default-Font auf "Liberation Sans". Danach müssen Sie iReport neu starten.


=== Fonts auf dem Server ===

Um Schriftarten auf einen Tomcat-Server zu installieren, müssen die vier ttf-Dateien (normal, fett, kursiv, fett-kursiv) in den Ordner $JRE_HOME/lib/fonts kopiert werden. Für alle Java Anwendungen wie den Tomcat und JasperReports stehen dann die in dem verwendetem Java zur Verfügung.

Beispiel Arial unter Ubuntu 18.04:

Prüfen Sie mit dem Kommando

ps fax | grep tomc

welcher Tomcat läuft. Sie bekommen eine Ausgabe z.B.

47769 ? Sl 36:25 /usr/lib/jvm/java-8-openjdk-amd64/bin/java -Djava.util.logging.config.file=/var/lib/tomcat8/conf/logging.properties -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Djdk.tls.ephemeralDHKeySize=2048 -Djava.protocol.handler.pkgs=org.apache.catalina.webresources -Xmx3500M -XX:MaxPermSize=400m -Djava.awt.headless=true -Dfile.encoding=UTF-8 -DSuperX-DB-PROPERTIES-SET=true -Djava.endorsed.dirs=/var/lib/tomcat8/endorsed -classpath /var/lib/tomcat8/bin/bootstrap.jar:/var/lib/tomcat8/bin/tomcat-juli.jar -Dcatalina.base=/var/lib/tomcat8 -Dcatalina.home=/var/lib/tomcat8 -Djava.io.tmpdir=/var/lib/tomcat8/temp org.apache.catalina.startup.Bootstrap start

Der erste Befehl zeigt den Pfad zu JRE_HOME, also /usr/lib/jvm/java-8-openjdk-amd64. Sie kopieren also die Dateien z.B.

arial.ttf

arialbd.ttf

arialbi.ttf

ariali.ttf

von

C:\Windows\winsxs\amd64_microsoft-windows-font-truetype-arial_31bf3856ad364e35_6.1.7601.17514_none_d0a9759ec3fa9e2d\*.ttf

nach

/usr/lib/jvm/java-8-openjdk-amd64/lib/fonts

und starten dann Tomcat neu.

<blockquote>Achtung: Sorgen Sie dafür dass Sie eine Lizenz für die jew. Fonts haben, weil diese bei PDF in die ausgelieferten Dateien eingebettet werden.
</blockquote>

=== Font Extension ===

Eine Alternative zu dem Einbinden der Schriftart über das Java Verzeichnise Font Extension. Diese hat aber nicht immer funktioniert. Um auf diesem Wege die Fonts auf einem Ziel-Server einzubinden, kann man die Schriftart als Font Extension exportieren, die dann wiederum in den CLASSPATH des Servers (bei Webanwendungen WEB-INF/lib) kopiert werden müssen:

[[Datei:JasperReports-Handbuch_font_import2.png]]

Nutzen Sie dazu den obigen Button "Export as extension", und wählen Sie einen Dateinamen mit der Endung ".jar".

<blockquote>Hinweis: Die Einbettung einer Font Extension in einer JasperReports-Laufzeitumgebung klappt erst mit JasperReports 3.7.2 oder höher.
</blockquote>
Wenn Sie in iReport auch PDF als Vorschau wählen, erzeugt iReport im Verzeichnis der jrxml-Datei auch eine entsprechende PDF-Datei. Damit diese die Fonts enthält, müssen Sie auch in iReport im CLASSPATH die Font-Extension einbinden. In diesem Falle ist es vorteilhaft, die Endung ".jar" (nicht ".zip") zu wählen, weil iReport hier nur jar-Dateien einbindet.

Noch ein Hinweis zu den Attributen "PDF Font name" und "PDF Encoding":

[[Datei:JasperReports-Handbuch_font_import3.png]]

Diese Attribute werden nicht mehr ausgewertet, wenn Sie mit Font Extensions arbeiten.


== TextField-Formatierung ==

In diesem Abschnitt werden verschiedene Einstellungen und Möglichkeiten der Formatierung in TextFields vorgestellt und erläutert.


=== Ausgabe von '''NULL''' als '''String''' verhindern ===

Falls NULL in einem TextField als String ausgeschrieben wird, kann dies verhindert werden, indem die Einstellung „Blank When NULL“ aktiviert wird. Das Feld bleibt dann leer:

[[Datei:JasperReports-Handbuch_text_field_formatting.png]]


=== Einzelne Wörter unterstreichen oder fett drucken ===

Wenn in einem TextField einzelne Wörter unterstrichen oder fett gedruckt werden sollen, einfach in den „Text properties“ unter „Markup“ „styled“ auswählen. In dem Textfield dann einfach um das zu unterstreichende Wort „ … “ schreiben oder „ … “ um es fett gedruckt auszugeben.

<blockquote>Bitte beachten, dass die PDF-Preview aus Jaspersoft Studio heraus keinen Fettdruck darstellt.
</blockquote>

=== Zahlen- und Datumsformat ===

Die Formatierung der Werte kann mit Hilfe des Attributes "Pattern" gesetzt

werden. Hier ein Beispiel:

[[Datei:JasperReports-Handbuch_textfield_pattern1.png]]

Das Textfeld bekommt das Pattern "0", d.h. es wird eine Ganzzahl inkl. 0 angezeigt. Der Platzhalter "#" steht für Zahlenbestandteile, hier wird eine 0 allerdings nicht angezeigt. Weitere Zahlen- und Datumsformate sind im Assistenten (linker Teil des Screenshots) sicher selbsterklärend.


=== Pattern Expression ===

Hat man pro Spalte / Zelle unterschiedliche Werte z.B. Datumsangaben und Währungseinheiten

oder Ganzzahlen und Kommazahlen und möchte diese unterschiedlich formatieren, so kann dies

mit dem Attribut "Pattern Expression" dargestellt werden.

Hier ein Beispiel für die Ausgabe von Ganzahlen und Kommazahlen:

$V{valueMeasure}.doubleValue() == Math.floor($V{valueMeasure}.doubleValue()) &&

!Double.isInfinite($V{valueMeasure}.doubleValue()) ?

"#0;#0" : "###0.00;###0,00"

Hier der Pattern Expression Editor:

[[Datei:JasperReports-Handbuch_ireport_pattern_expression_editor.png]]

Hier das Ergebnis:

[[Datei:JasperReports-Handbuch_ireport_pattern_expression_ergebnis.png]]


== Effiziente Formatierung ==

Wenn Sie keine Lust haben, jedes Textelement eines Berichts einzeln zu formatieren, empfehlen wir als ersten Schritt, Formatierungen zu kopieren.

Im Kontextmenü jedes Elements gibt es die Menüpunkte "Copy Format" und "Paste Format", die jeweils Formate kopieren und einfügen.

[[Datei:JasperReports-Handbuch_copy_format.png]]

Für Hochschulen ist ein einheitliches Layout der Berichte wichtig, und so bietet es sich an, zentrale Layouts zu definieren und dann wiederzuverwenden. In JasperReports heißen Layouts auch "Styles" bzw. Formatvorlagen. Ähnlich wie in OpenOffice Writer oder MS Word lassen sich Formatvorlagen definieren und zuweisen. Bei Änderungen der Formatvorlage werden diese Änderungen auf alle Elemente automatisch übertragen - auch nachträglich.

In der "Styles Library" werden z.B. einige häufig verwandte Layoutvorlagen angeboten.

[[Datei:JasperReports-Handbuch_styles_library.png]]

Sie können die Formate anwenden, indem Sie einfach die jew. Vorlage von der "Styles Library" per Drag and Drop auf das Ziel-Textfeld im Report Design ziehen und somit anwenden.

Sie können auch eigene Formatvorlagen zentral definieren. Im Menü Datei->New->Style geht es los: Wir erzeugen z.B. eine neue Style-Datei mit dem Namen "meinLayout.jrtx":

[[Datei:JasperReports-Handbuch_style_def_folie.png]]

In der jrtx-Datei definieren sie einen oder mehrere Formatvorlagen. Wir definieren z.B. die Formatvorlage "Textelemente", und geben ihr die Eingenschaft "SansSerif, Schriftgröße 12".

Danach können sie die Datei in der jrxml-Datei im Report Inspector unter "Styles" einbinden. Damit sind die Formatvorlagen in dieser Datei verfügbar, und können bei den Elementeigenschaften im Attribut "Style" zugewiesen werden:

[[Datei:JasperReports-Handbuch_styleref_design_folie.png]]

JasperReports nimmt standardmäßig den absoluten Pfad der jrtx-Datei, in der XML-Quelle sollten Sie diesen Pfad auf relativ umstellen.


== Conditional styles – '''Bedingte Formatierung''' ==

Wenn man in einzelne Textfelder "bedingte Formatierung" nutzen will (z.B. farbiger Hintergrund, Fettdruck), hat man früher mehrere Textfelder einzeln angelegt, mit dem gleichen Inhalt und einer jeweiligen "Print-when expression". Das geht seit JR 3.x eleganter mit den sog. "Conditional styles".

Hierfür wird ein Style angelegt und diesem diverse „Conditional Styles“ untergeordnet. Die „Conditional Styles“ enthalten Bedingungen und Formatierungseinstellungen. Der Style kann beispielweise einem Textfeld übergeben werden. Sobald die Bedingung eines „Conditional Styles“ erfüllt wird, werden die im „Conditional Style“ festgelegten Formatierungseinstellungen auf das Textfeld angewandt. Die Einstellungen im Textfeld selbst werden allerdings höher priorisiert. Eine detaillierte Erläuterung der Priorisierung anhand eines Beispiels findet sich in Abschnitt „Textfeld vs. Conditional Style – Priorisierung“


=== Beispiel in JasperSoft Studio – Schrift fett machen ===

Zunächst legen Sie die Formatierungen an, indem Sie unter Styles die rechte Maustaste drücken und über „Create Style“ einen Style erstellen, beispielsweise '''Daten_angepasst'''.

[[Datei:JasperReports-Handbuch_cond_style3.png]]

Durch Rechtsklick auf '''Daten_angepasst''' wird über „Create Conditional Style“ ein neuer Conditional Style hinzugefügt. Es erscheint ein neuer Unterknoten <No condition set>. Über die Properties können anschließend die zu erfüllende Bedingung als Expression, beispielsweise

''$F{Name}.equals("Summe Aktiva")||$F{Name}.equals("Summe Passiva")''

festgelegt und die Formatierungseinstellungen vorgenommen werden. In diesem Falle ist Fettschrift (bold) gewählt :

[[Datei:JasperReports-Handbuch_cond_style4.png]]

Um den Style inklusive seiner Conditional Styles auf beispielsweise ein Textfeld anzuwenden, werden die Properties des entsprechenden Feldes geöffnet. Im Reiter Appearance wird der gewünscht Style, in diesem Falle '''Daten_angepasst''',''' '''dem Textfeld zugeordnet:

[[Datei:JasperReports-Handbuch_cond_style5.png]]

Bei mehreren conditional styles wird die Reihenfolge ausgewertet, alle zutreffende conditional styles werden genommen. Die Reihenfolge wird direkt im XML oder per Drag&Drop geändert.

Es kam in der Vergangenheit bereits zu dem Phänomen, dass im Conditional Style Fettschrift gewählt war, aber nicht ins Textfeld übernommen wurde, während beispielsweise Kursivschrift problemlos und wie erwartet funktionierte. Eine genauere Beschreibung und Lösung findet sich im Abschnitt „Textfeld vs. Conditional Style – Priorisierung“


=== Beispiel in iReport – Schrift fett machen ===

Um z.B. einzelne Zeilen nach einer Bedingung fett zu machen oder nicht kann man so vorgehen: Zunächst legen Sie die Formatierungen an, indem Sie im Report Inspector unter Styles die rechte Maustaste drücken und ein Style hinzufügen, z.B. '''zw_maybe_bold''' für einen Style der Fett sein soll, wenn im Feld '''zw''' bestimmte Werte stehen.

[[Datei:JasperReports-Handbuch_styles.png]]

Danach erzeugen Sie mit Rechtsklick auf '''zw_maybe_bold''' eine neue Bedingung mit „Hinzufügen von Conditional Style“. Bei dem neuen Unterknoten <No condition set> klicken Sie auf die rechte Maustaste, dann Edit Condition. Hier können Sie wie gewohnt eine Bedingung in Form einer Expression eingeben, z.B.

$F{Zweckbestimmung}.equals("Gesamtausgaben")||$F{Zweckbestimmung}.equals("Gesamteinnahmen")

Dann müssen Sie den neuen Conditional Style anklicken

[[Datei:JasperReports-Handbuch_cond_style.png]]

und in den Eigenschaften bold auf true setzen.

Dann wählt man im Report designer die Felder aus, die ggfs. fett dargestellt werden sollen, und bei den Eigenschaften als Style '''zw_maybe_bold'''.

[[Datei:JasperReports-Handbuch_cond_style2.png]]

Wenn man mit Padding arbeiten will, kann man für den Style padding angeben, muss aber anscheinend manuell im jrxml leftpadding entfernen

<box topPadding="0" <s>leftPadding="0"</s> bottomPadding="0">

Bei mehreren conditional styles wird die Reihenfolge ausgewertet, alle zutreffende conditional styles werden genommen. Es gibt zwar einen Menüpunkt „Reihenfolge ändern“ bei rechtem Mausklick, der ist jedoch deaktiviert, man kann die Reihenfolge aber direkt im XML ändern oder per Drag&Drop.

Leider kann man nicht einen conditionalstyle auf ein leere Zelle anwenden (z.B. Unterstrich), wenn man Excelexport macht, wird daraus einfach eine leere Zelle ohne Formatierung selbst wenn man Leerzeichen in der Text Expression hat.

Werden Variablen im conditional style verwendet, muss die evaluation time aktiviert werden über die property:

<property name="net.sf.jasperreports.style.evaluation.time.enabled" value="true"/>

Siehe https://community.jaspersoft.com/blog/tip-data-set-variable-usage-conditional-style-table-component-jasper-reports

Ein Style kann auch mit einem anderen Style verknüpft werden, indem in dem entsprechenden Style unter dem Reiter „Style“ in dem Feld „Style“ das entsprechende Style ausgewählt wird. Somit können bestimmte Wiederholungen gespart werden.


=== Textfeld vs. Conditional Style – Priorisierung ===

In diesem Abschnitt wird anhand eines Beispiels aufgezeigt, dass Textfelder höher priorisiert sind als Conditional Styles und welche Fallstricke dadurch entstehen können. Das Beispiel:

Einem Textfeld wird ein Style zugeordnet, der einen Conditional Style enthält, welcher bei erfüllter Bedingung den Text fett und kursiv darstellen soll:

[[Datei:JasperReports-Handbuch_cond_style6.png]]

Im Textfeld selbst sind beide Einstellungen deaktiviert:

[[Datei:JasperReports-Handbuch_cond_style7.png]]

Das Ergebnis ist, dass im Bericht der Text dieses Feldes zwar kursiv, aber nicht fett dargestellt wird. Zum Testen werden weitere Formatierungseinstellungen im Conditional Style hinzugefügt, beispielsweise Unter- und Durchstreichen und auch dies wird umgesetzt. Die Bedingung des Conditional Styles ist also erfüllt.

Der Grund für dieses Verhalten ist nur mit Blick auf den Source-Code ersichtlich:

[[Datei:JasperReports-Handbuch_cond_style8.png]]

Dort findet sich in den Einstellungen des Textfeldes ''isBold=“false“''. Dieses Fragment ist dadurch entstanden, dass in der Designoberfläche von JasperSoft Studio für das Textfeld die Einstellung bold einmal aktiviert und dann wieder deaktiviert wurde. Im Source-Code wird nach dem ersten Aktivieren ''isBold=“true“'' hinzugefügt und beim Deaktiveren nicht wieder komplett entfernt, sondern auf false gesetzt. Da die Einstellungen im Textfeld selbst höher priorisiert werden, als jene der Conditional Styles, wird der Fettdruck des Conditional Styles nicht umgesetzt. Löscht man im Source-Code das Fragment ''isBold=“false“'', dann wird der im Conditional Style definierte Fettdruck umgesetzt.


=== Default Style ===

Es ist möglich einen Style als Default Style zu verwenden. Hierfür wird beim Style, nicht beim Conditional Style, die entsprechende Einstellung gesetzt:

[[Datei:JasperReports-Handbuch_cond_style9.png]]

Dieser Style wird nun auf jedes Feld angewandt, dem kein anderer Style zugeordnet ist.


== Expression Editor ==

Im Expression Editor werden die für die Ausgabe bestimmten Werte angegeben. Zahlen werden ohne Zusatz eingetragen. Feste String Werte werden zwischen Anführungszeichen gesetzt. Felder und Variablen können über ein Doppelklick auf den jeweiligen Namen unterhalb des Eingabefeldes eingefügt werden.

[[Datei:JasperReports-Handbuch_ireport_filter1.png]]

Zu den Feldern und Variablen gibt es auch noch Funktionen in dem 3. unterem Kästchen.

Ein Beispiel für Textausgabe:

Es soll ausgegeben werden „Auswertungszeitraum 1.1.<<Jahr>> bis 31.12.<<Jahr>>“.

Anstatt zwei statische Textfelder und zwei dynamische zu machen, legt man eine Expression an:

"Auswertungszeitraum: 1.1."+$F{legende_Jahr_value}+" bis 31.12."+$F{legende_Jahr_value}

<blockquote>Der Clou an JasperReports ist: da das Programm auf der Programmiersprache Java beruht, kann man in Expressions echten Java Code einfügen bzw. um eigenen Java Code erweitern. Wenn Sie z.B. wissen dass das benutzte Feld "$F{Lehr- und Forschungsbereich}" vom Typ String ist, können Sie alle in Java eingebauten String Funktionen benutzen, z. B. Substring, contains, indexOf, toLowerCase etc. Analog auch für andere Datentypen.
</blockquote>

=== Bedingungen ===

Bedingungen sind in dem Expression Editor auch möglich. Wenn z.B. eine Variable nur Ausgegeben werden soll, wenn der Wert größer, kleiner oder gleich einem anderem vorgegebenen Wert oder Variable sein soll, wird folgende Syntax verwendet:

<<Bedingung>> ? <<Ausgabe wenn Bedingung wahr>> : <<Ausgabe wenn Bedingung falsch>>

Bedingungen:

String1 == String2

String1 != String2

Nummer1 > Nummer2

String1.contains( String2 )

String1 == null

usw.

Wie oben angegeben: Wenn die Bedingung wahr ist, wird der Wert nach dem Fragezeichen genommen. Wenn die Bedingung falsch ist, wird der Wert nach dem Doppelpunkt genommen.


=== Umgang mit Zeichenketten ===

Häufig werden für Berichtsausgaben Zeichenketten manipuliert. Dadurch, daß JasperReports innerhalb der Java-Runtime läuft, stehen uns mächtige Methodenaufrufe zur Verfügung, die in Java schon eingebaut sind.

Für Zeichenketten hier eine Übersicht:

http://docs.oracle.com/javase/7/docs/api/java/lang/String.html


=== Umgang mit Datumsfeldern ===


==== Datumswerte aggregieren ====

Fürs Berichtsdesign auf aggregierter Ebene ist es oft praktisch, Datumswerte auf "grobere" Kategorien zu aggregieren, z.B. Monate, Quartale, oder Jahre. Um solche Werte auszugeben bzw. danach zu gruppieren können Sie eigene Variablen anlegen, die dann im Expression Editor mit Hilfe von Java berechnet werden. Hier ein Beispiel für eine Transformation vom Datum zur Einheit "Jahr-Monat":

(($F{Datum}.getYear()+1900)*100)+($F{Datum}.getMonth()+1)

Wenn wir annehmen, dass im Feld "Datum" ein Datums- oder Zeitstempel-Wert steht, dann wird über die o.g. Expression daraus ein Zahlenwert nach dem Muster Jahr (vierstellig) + Monat (zweistellig), z.B. für den 13.5.2013 würde daraus der Wert 201305. Nach diesem ganzzahligen Wert kann man dann sortieren und gruppieren.

<blockquote>Anmerkung: die o.g. Methoden getYear() und getMonth() sind seit einigen Jahren in Java "deprecated", d.h. sie könnten in zukünftigen Java Versionen entfallen. Aber da dies in den letzten 7 Jahren nicht passiert ist, können wir damit noch arbeiten und optimistisch sein. Falls die Methoden wirklich entfernt werden, muss man eigene statische Methoden mit dem in Java eingebauten Calender-Objekt erstellen, Codebeispiele dazu gibt es viele im WWW.
</blockquote>

wenn man Text "Erzeugungsdatum" und das Datum in einem Feld haben will geht so: 
"Erzeugungsdatum:"+new SimpleDateFormat("dd.MM.YYYY", Locale.GERMAN).format(new java.util.Date())


==== Zeichenketten zum Datumstyp konvertieren ====

Wenn Sie ein Datum als String-Feld geliefert bekommen, können Sie es mit Groovy zum Typen "java.util.Date" konvertieren, z.B. um danach zu sortieren. Wenn z.B. das Feld „Beginn“ den Typ String hat und gefüllt ist mit dem Wert "18.11.2020 18:05:00", dann können Sie eine Variable vom Typ java.util.Date erzeugen, mit der Expression:

Date.parse("dd.MM.yyyy hh:mm:ss", $F{Beginn})


=== Besonderheiten / Workarounds ===

* Bei Feldern mit Länge 1 klappte einfaches equals nicht, mit einer substring Anweisung geht es dann:

$F{legende_Art des Berichts_value}.substring(0,1).equals("B")

* Folgejahr berechnen: Selbst es das Feld Jahr gibt und es als Integer definiert ist in der Felderinfo, klappt der Bericht nur in JasperReports nicht in SuperX nicht wenn man schreibt: 
$F{legende_Jahr_value}.intValue()+1 
geht nicht, statt dessen: 
new Integer($F{legende_Jahr_value}).intValue()+1
* Statt das Element table zu nutzen kann man auch manuell eine Tabelle erzeugen, in dem man per Rechtsklick auf ein Element Padding und Borders bearbeitet. Siehe http://www.youtube.com/watch?v=LbU6qTj3zQM
* Achten muss man dann darauf, dass Felder die Null sein können nicht „remove when blank“ haben und als TextFieldExpression besser nehmen: $F{Betrag}==null?" ":$F{Betrag}
* außerdem, wenn die erste Spalte einen stretch with overflow hat auch bei „stretch type“ „relative to tallest object“ einstellen
* Zeilenumbruch in Feld 
Markup auf html setzen und dann z.B. "Plan'''''' ''''''"+$F{legende_Jahr_value}


=== Häufig benötigte Transformationen ===


==== Umrechnung Semester-tid in Namen ====

$V{Semester (Schlüssel)}.toString().endsWith("1")?("SS "+$V{Semester (Schlüssel)}.toString().substring(0,4)):("WS "+$V{Semester (Schlüssel)}.toString().substring(0,4)+"/"+(new Integer($V{Semester (Schlüssel)}.toString().substring(0,4))+1).toString())


==== Umrechnung Semester in akad. Jahr ====

Die folgende Formel formt die Semesterzahl aus dem Studierenden-Datenblatt in ein akad. Jahr um nach der Formel "Akad. Jahr=WS + darauf folgendes SS", z.B. WS 2009/2010 und SS 2010 werden zum akad. Jahr 2009:

$F{Semester der Belegung (Schlüssel)}.toString().endsWith("2") ? $F{Semester der Belegung (Schlüssel)}.toString().substring(0,4):(new Integer($F{Semester der Belegung (Schlüssel)}.toString().substring(0,4))-1).toString()

Die Formel nimmt beim WS die ersten vier Stellen des Semester-Schlüssels, und beim SS werden die ersten vier Stellen als Ganzzahl codiert, und dann wird 1 subtrahiert.

Da es diverse Definitionen von Akad. Jahr / Studienjahr / Prüfungsjahr gibt, kann man das obige Beispiel leicht für eigene Bedürfnisse abwandeln.


== Pattern Expression ==

Die Formatierung der Werte kann mit Hilfe des Attributes "Pattern" gesetzt

werden. Hat man allerdings unterschiedliche Werte z.B. Datumsangaben und Währungseinheiten

oder Ganzzahlen und Kommazahlen und möchte diese unterschiedlich formatieren, so kann dies

mit dem Attribut "Pattern Expression" dargestellt werden.

Hier ein Beispiel für die Ausgabe von Ganzahlen und Kommazahlen:

$V{valueMeasure}.doubleValue() == Math.floor($V{valueMeasure}.doubleValue()) &&

!Double.isInfinite($V{valueMeasure}.doubleValue()) ?

"#0;#0" : "###0.00;###0,00"

Hier der Pattern Expression Editor:

[[Datei:JasperReports-Handbuch_ireport_pattern_expression_editor.png]]

Hier das Ergebnis:

[[Datei:JasperReports-Handbuch_ireport_pattern_expression_ergebnis.png]]


== Fortgeschrittene Techniken bei Feldern ==

Textfelder enthalten standardmäßig nur den Feldnamen, aber die zugrunde liegenden [[#2.9.Expression Editor|outline|Ausdrücke]] lassen sich erweitern. Dabei kann auch alle Java Klassen zugegriffen werden, die sich im CLASSPATH befinden, z.B. [[#2.9.2.Umgang mit Zeichenketten|outline|java.lang.String]].

Hier ist ein Beispiel, in dem die Klasse "StringBuilder" (wird mit Java ausgeliefert , java.lang.StringBuilder) genutzt wird, um einen Text auszugeben:

[[Datei:JasperReports-Handbuch_expression_stringbuilder.png]]

Im Ergebnis sieht das so aus:

[[Datei:JasperReports-Handbuch_expression_stringbuilder1.png]]

Das Beispiel verdeutlicht: Man könnte da auch de.meineKlasse.erzeugeText("mein Text") schreiben, und diese Klasse dann in den CLASSPATH bei Jasper Start legen, und voila! Durch diese Funktionalität lassen sich also beliebige Java Klassen einbinden. Das gleiche geht übrigens auch mit Groovy.


== Einrücken von Feldern ==

Das Einrücken von Feldern macht man am besten, in dem man mehrere Textfelder definiert und jeweils eine printWhenExpression auf die Ebene einbaut.

Alternativer Versuch war folgendes:

Wobei Nachteil bei sehr langen Texten, bei denen strech with overflows zur Geltung kommt, dann die zweite Zeile nicht eingerückt wird.

Das Einrücken von Felder kann man für Textfelder (Strings) machen, indem der SuperX-Bericht eine Spalte einruecken definiert, der je nach gewünschter Einrückung eine Anzahl von x enthält, also z.B.

{| class="wikitable"
|-
!
!
!
|-
| Name
| Betrag
| Einrücken
|-
| 1. Überschrift
| 30000
| X (mindestens 1 x nötig)
|-
| 1.1 Unterüberschrift
| 15000
| Xxxxx
|-
| 1.3. UnterUnterübersichrift
| 3000
| xxxxxxxxx
|}

Dann kann man ein Textfeld erzeugen und bei TextFieldExpression einfach eintragen:

$F{Einruecken}.replace('x',' ')+$F{Name}

Für Zahlfelder (z.B. Double) geht das so nicht so gut, weil dann das Pattern der Darstellung ###0,00 nicht mehr greift.

Man definiert drei Felder nebeneinander, Beispiel:

{| class="wikitable"
|-
!
!
!
|-
| $F{Name}
| ${Betrag}

PrintWhenExpression

$F{Hierarchie_Ebene}.intValue()>=6

| ${Betrag}

PrintWhenExpression

$F{Hierarchie_Ebene}.intValue()<6

|}

Bei Ebene 1-5 wird ganz rechts ausgegeben, bei Ebene >=6 wird mittig ausgegeben.


== Berechnungen ==

Bei Berechnungen muss immer auch auf (ich nenne es mal) die Gültigkeit der Variable geachtet werden. Wenn eine Variable eine Summe bildet kann diese für z.B. „jetzt“ oder für eine Gruppe oder den ganzen Report gelten. Je nach Gültigkeit gilt z.B. die Summe nur für die aktuelle Gruppe (bei Gruppenbändern).

Achtung: Es gibt nicht nur eine Gültigkeit bei der Variable selber (Reset type) sondern auch bei dem Element in dem Bericht. Wenn eine Variable in den Bericht gezogen wird, besitzt das entstandene Element eigene Eigenschaften, bei dem dann die „Evulation Time“ eingestellt werden kann.


=== Prozentrechnung ===

Für die Prozentrechnung musst zuerst eine Variable z.B. mit dem Namen "Gesamt" anlegen mit den Eigenschaften:

Calculation = Sum

Reset type = Report

Dannach kann ein Textfeld mit dem Inhalt:

$F{Summe} / $V{Gesamt}

erstellt werden mit den Eigenschaften:

Expression Class = Double

Pattern = #.##0.00 % (kannst du unter Prozent auswählen)

Evaluation Time = Auto

In der Variable „Gesamt“ wird die Summe aus allen Werten des Feldes Summe gezogen.

Bei Prozentberechnungen in Grafiken muss in manchen Fällen der Wert auf 0 überprüft werden. Das kann man z.B. mit folgendem Code machen:

( $V{zahl1} == 0 || $V{zahl2} == 0 ? 0 : ( $V{zahl1} / $V{zahl1} * 100) )

Damit ist dann sichergestellt, dass es keine Probleme bei der Berechnung gibt, auch wenn die Zahlen mal leer sind.


=== Rundung ===

Wenn man runden möchte den Datentyp am besten auf BigDecimal stellen. Ansonsten wird schon mal aus 2,45 gerundet 2,4.


== Hyperlinks ==


=== Externe Links ===

Ein Textfeld kann auch als Hyperlink befüllt und ausgegeben werden. Vorab bemerkt: Hyperlinks funktionieren in internen Viewer von JasperSoft Studio sowie beim Export nach Excel nicht bzw. nur eingeschränkt, zumindestens wenn man POI als Excel Engine nutzt. Selbst wenn Hyperlinks ausgegeben werden, ist in den Sicherheitseinstellungen von Excel oder OpenOffice eine Änderung vorzunehmen, damit Hyperlinks auch aktiv sind. Da es hier komplexte Unterschiede bei MS Excel-/OpenOffice-Versionen gibt, haben wir das Thema nicht weiter verfolgt und raten davon ab.

In den anderen üblichen Ausgabeformaten (PDF, HTML) funktionieren die Hyperlinks.

Dabei gibt es zwei Varianten:

Das Textfeld hat als Markup Typ den Wert "html", und die Hyperlinks werden in HTML-Notation eingefügt. Beispiel:

[[Datei:JasperReports-Handbuch_hyperlink_pfd3.png]]

Hier der Quellcode der textField-Expression zum Kopieren:

$V{Gross_Forsch_Proj_Sprech}.replaceAll( "\n"," " )+"<a href=\"http://www.meinserver.de/url/\">Siehe Details</a>"

Im Ergebnis sieht das dann so aus:

[[Datei:JasperReports-Handbuch_hyperlink_pfd2.png]]

Bei Variante 2 erhält ein ReportElement im Quellcode die entsprechende Eigenschaft. In der von uns genutzten Version von JasperSoft Studio (6.5.1 final) war das noch nicht im GUI bearbeitbar, daher kann man das nur im Quelltext machen. Immerhin "zerstört" JasperSoft Studio dies beim Speichern nicht.

Die Eigenschaft des textField heißt hyperlinkType="Reference" und wird wie folgt belegt:

<textField pattern="" isBlankWhenNull="true" '''hyperlinkType="Reference"'''>

<reportElement mode="Opaque" x="363" y="22" width="259" height="22" forecolor="#000000" backcolor="#FFFFFF" uuid="48c8e2df-f231-4433-8836-309668e0a859">

<printWhenExpression><![CDATA[$V{Gross_Forsch_Proj_Sprech}.length() >100]]></printWhenExpression>

</reportElement>

<box>

<pen lineWidth="0.5"/>

<topPen lineWidth="0.5"/>

<leftPen lineWidth="0.5"/>

<bottomPen lineWidth="0.5"/>

<rightPen lineWidth="0.5"/>

</box>

<textElement textAlignment="Left" verticalAlignment="Middle" rotation="None" markup="html">



<paragraph lineSpacing="Single"/>

</textElement>

<textFieldExpression><![CDATA["Siehe Details"]]></textFieldExpression>

'''<hyperlinkReferenceExpression><![CDATA["http://meinserver/url"]]></hyperlinkReferenceExpression>'''

</textField>

Am Ende des textField wird dann im Element hyperlinkReferenceExpression das Ziel des Hyperlinks definiert. Da dies eine Expression ist, kann man die Hyperlinks auch dynamisch aufbauen. In der Ausgabe dies das dann so aus:

[[Datei:JasperReports-Handbuch_hyperlink_pdf.png]]

Je nach PDF Viewer muss man auch hier in den Sicherheitseinstellungen Hyperlinks aktivieren.


=== Interne Links/Anker ===

Auf einem Text Field kann ein Link eingetragen werden. Dafür muss man einfach mit der rechten Maustaste auf das Textfeld klicken und dann auf Hyperlink klicken.

Das erste Feld oben „Anchor Name Expression“ kann einen Text enthalten, auf den von einer anderen Stelle verwiesen werden kann. Es ist also eine Markierung.

Wenn ich einen Hyperlink Type wähle, kann ich auch Verweise in den generierten Bericht erzeugen. Z.B. kann ich hier den Type „LocalAnchor“ wählen.

Um z.B. ein Inhaltsverzeichnis zu erzeigen, welches im PDF bei klick auf ein Element dort hin springen soll, gehe ich zunächst zu der Stelle an der die Sprungmarke gesetzt werden soll und erzeuge dort ein Text Field mit der „Anchor Name Expression“ z.B. „Überschrift1“. Das Inhaltsverzeichnis muss dann auch aus Text Fields erzeugt werden und dort wähle ich dann bei Hyperlink type „LocalAnchor“. Nun habe ich unter der Auswahl von dem Hyperlink type ein neues Eingabefeld „Hyperlink Anchor Expression“. Dort trage ich jetzt exakt den gleichen Text „Überschrift1“ ein und im generierten PDF kann ich dort drauf klicken um an die Markierte Stelle zu kommen.


== Berichts-Properties setzen ==

Es gibt auf Berichtsebene die Möglichkeit, die Ausgabe der Berichte über sog. "Properties" zu steuern, teilweise auch formatspezifisch. So können Sie z.B. steuern, daß bei der Ausgabe nach Excel Zahlenfelder als Zahlenfelder ausgegeben werden, nicht als Textfelder.

Um die Berichts-Properties zu setzen, können Sie dies entweder für einzelne Berichte, order auch Server-weit einstellen.

Bei einzelnen Berichten gehen Sie im Report Inspector auf das oberste Element, und dort auf "Eigenschaften".

[[Datei:JasperReports-Handbuch_report_properties1.png]]

Sie erhalten dann eine Liste der Eigenschaften:

[[Datei:JasperReports-Handbuch_report_properties2.png]]

Dort können Sie Zeilen hinzufügen, bearbeiten und löschen. Eine Erläuterung der jew. Property erhalten Sie in dem jew. Dialog.

Um eine Property systemweit zu speichern, legen Sie eine Textdatei mit dem Namen "jasperreports.properties" an, und legen diese in den CLASSPATH. Im Kontext von Tomcat ist dies das Verzeichnis webapps/superx/WEB-INF/classes.


== Seitenlayout ==


=== Seitenumbrüche ===

Es gibt drei Typen von Seitenumbrüchen:

* Wenn der gesamte Bericht paginiert ist (Report-Eigenschaft "Ignore Pagination"="false"), berechnet JR aufgrund des Seitenformats die Seitenumbrüche automatisch, und fügt auch, sofern vorhanden, die Bänder "page header" und "page footer" hinzu.
* Bei eingeschalteten Eigenschaften des jew. Bandes "Start on a new page=true" werden Seitenumbrüche ebenfalls aufgeführt
* Es gibt für manuelle Seitenumbrüche in der Palette das Element "Break", das an beliebiger Stelle einen manuellen Seitenumbruch einfügt. Nun ist die Frage: wenn gesamte Bericht nicht paginiert ist ("Ignore Pagination"="true"), was dann bei einem Break passieren soll. In älteren JR Versionen (vor 4.8) wurde der Break trotzdem gesetzt. In Versionen ab 4.8 passiert das nicht mehr, man kann aber ab Version 5.1 über die Berichts-Property 
net.sf.jasperreports.page.break.no.pagination=apply 
das alte Verhalten nachbilden.

In JasperSoft Studio oder iReport kann man zusätzlich noch beim Rendern des Berichts über den Parameter JRParameter.IS_IGNORE_PAGINATION steuern, ob Seitenumbrüche ausgeführt werden. Dies überlagert die Berichtseinstellung, wenn es angehakt ist. Das ist z.B. sinnvoll, wenn Sie im PDF Export Seitenumbrüche haben wollen, in Excel oder HTML aber nicht.

Leider kann man diesen Parameter nicht im Servlet setzen. Wenn Sie Seitenkopf/Fuß bei PDF wünschen, bei Excel aber nicht, nutzen Sie die Anleitung [[#2.21.5.Seitenkopf und Seitenfuß bei Excel unterdrücken|outline|unten]].

Es gibt verschiedene Möglichkeiten, wie sich das Detailband bei einem Seitenumbruch verhalten soll. Diese werden über den ‚Split Type‘ des Bandes gesteuert. Beispiel:

Bei einem Seitenumbruch wird die aktuelle Zeile des Detailbandes aufgeteilt und geht auf der nächsten Seite weiter. Der ‚Split Type‘ steht auf Stretch.

[[Datei:JasperReports-Handbuch_Eingebettet_011.png|642x170px]]

Falls erwünscht ist, dass jede Zeile ganz dargestellt wird, kann der ‚Split Type‘ auf Prevent gestellt werden:

[[Datei:JasperReports-Handbuch_Eingebettet_012.png|300x281px]]Das Ergebnis sieht wie folgt aus:

[[Datei:JasperReports-Handbuch_Eingebettet_013.png|642x223px]]


=== Die Höhe von Textfeldern dynamisch anpassen ===

[[Datei:JasperReports-Handbuch_layout1.png]]

Textfelder besitzen die Eigenschaft „Stretch With Overflow“. Wird diese aktiviert, passt das Textfeld dynamisch seine Größe, falls der Inhalt nicht in das Feld passt. Der Text bricht um und die Höhe des Feldes wird vergrößert. Damit auch alle anderen Felder derselben Zeile ihre Größe entsprechend anpassen wird der „Stretch Type“ aller Felder dieser Zeile auf „Relative To Tallest Object (deprecated)“ gesetzt. Die Felder passen ihre Höhe dann dem höchsten Feld dieser Zeile an. Im Detailband genügt dies. Für Bänder mit festgelegter Zeilenanzahl, wie beispielsweise dem Titelband ist eine weitere Einstellung vorzunehmen.

Um im Titelband die Funktion „Stretch With Overflow“ nutzen zu können, ist es notwendig allen Feldern in darunterliegenden Zeilen den „Position Type“ „Float“ zuzuweisen. Die Position der Felder verändedrt sich dann entsprechend der Höhe darüberliegender Felder.

[[Datei:JasperReports-Handbuch_layout2.png]]


=== Bericht ausgeben, ohne Dateninput ===

Wenn der Bericht bzw. das Layout mit Titelband etc. ausgegeben werden soll, obwohl es keine Daten gibt, dann wird die Funktion ‚When No Data Type‘ auf ‚All Sections No Detail‘ gestellt.

[[Datei:JasperReports-Handbuch_Eingebettet_014.png|336x374px]]


== Besonderheiten beim Export nach Excel ==

Für jedes Exportformat gibt es auf Berichtsebene bzw. darunter spezielle Properties, die Feinheiten des Zielformates festlegen. Dies wird im folgenden anhand des Excel-Exports von Formeln und Namen von Arbeitsblättern (Sheet-Names) gezeigt.

Bitte beachten Sie dass diese Hinweise für den "alten" Excel Export ("xls") gelten. Für die Exportformate xlsx, JExcel-API oder OpenOffice-Spreadsheets funktionieren diese teilweise nicht.

Um leere Zeilen im Excelexport zu vermeiden, im jrxml-Kopf:

<property name="net.sf.jasperreports.export.xls.collapse.row.span" value="true"/>

<property name="net.sf.jasperreports.export.xls.remove.empty.space.between.columns" value="true"/>

<property name="net.sf.jasperreports.export.xls.remove.empty.space.between.rows" value="true"/>

wenn man Zahlenanpassung möchte

<property name="net.sf.jasperreports.export.xls.auto.fit.row" value="true"/>

<property name="net.sf.jasperreports.export.xls.font.size.fix.enabled" value="true"/>

→ font wird ggfs. verkleinert

<property name="net.sf.jasperreports.print.keep.full.text" value="true"/>


=== Excel-Formeln ===

Es gibt auch die Möglichkeit Zahlen nicht nur vorab zu berechnen, sondern beim Export nach Excel als Excel-Formel zu übergeben.

Um diese Funktion zu aktivieren muss im JRXML die Property mit folgender Zeile eingefügt werden:

<property name="net.sf.jasperreports.export.xls.detect.cell.type" value="true"/>

Oder über die Report Properties:

[[Datei:JasperReports-Handbuch_excel_export_detect_cell_type1.png]]

Danach können in jedem Text Field in der Property expression:

[[Datei:JasperReports-Handbuch_excel_export_detect_cell_type2.png]]

folgende Einträge ergänzt werden:

[[Datei:JasperReports-Handbuch_excel_export_detect_cell_type3.png]]

Rechts neben net.sf.jasperreports.export.xls.formula wird die Formel für Excel eingetragen, allerdings ohne = am Anfang. Außerdem werden nicht alle Excel-Formeln unterstützt, insbesondere nicht deren deutsche Lokalisierung (z.B. oben SUMME(D119...). Details finden Sie in der [https://poi.apache.org/spreadsheet/formula.html POI]-Dokumentation. Um zu erfahren wie die Felder lauten, welche berechnet werden sollen, am besten den Bericht einmal ausführen und in Excel anzeigen lassen. Achtung: Wenn der Bericht noch bearbeitet wird, können sich die Felder noch verändern.

Bei net.sf.jasperreports.export.xls.pattern können speziell für Excel Formatangaben gemacht werden. In dem obigen Beispiel "#,##0.00;-#,##0.00" gibt es 2 Nachkommastellen und ein Tausender-Trennzeichen. Wenn z.B. Tausende von Euro angezeigt werden sollen, nimmt man als Pattern #.

<blockquote>Fallstrick: in der von uns getesteten Version (4.1.3) wurde die Property net.sf.jasperreports.export.xls.formula nur dann ausgewertet, wenn das das jew. Textfeld eine korrekte "Text field expression" hat, sie darf also nicht leer sein. Ob das ein Bug ist oder nicht ist uns derzeit unklar.
</blockquote>
Beispiel für eine komplexe Summenformel SUM(D7:D20,D28,D33,D40)

Man kann die Formel auch als Expression formulieren, z.b. um eine Division durch 0 zu verhindern. Setzen Sie dazu das Häkchen bei "Use an expression":

[[Datei:JasperReports-Handbuch_excelformula_expression.png]]

Das obige Beispiel führt die Formel "D91/D149" nur aus, wenn die Variable $V{Haush_Professoren_1} (die Quelle für die Zelle D149) einen Wert größer 0 hat. Wenn nicht, wird keine Formel reingeschrieben, sondern der Wert 0.

Diese Funktion bietet natürlich noch viel mehr Möglichkeiten, z.B. könnte man damit Excel-Zellennummern dynamisch berechnen etc. Beispiele dazu finden Sie in den JasperReport Demos in demo/samples/xlsformula/reports/XlsFormulaReport.jrxml.


==== Zeilennummern dynamisch berechnen (Ein Beispiel) ====

Will man dass in der gesamten Exceldatei immer Spalte F=D+E ist, braucht man nicht für jede Zeile feste Formeln eintragen.

Als Erstes schaut man in welcher Zeile die eigentlichen Daten anfangen, also z.B. nach den zwei Headerzeilen ganz am Anfang der Tabelle und den 3 Spaltenüberschriften, die pro Seite wiederholt werden.

Hier ein Beispiel

($F{Zweckbestimmung}.isEmpty()||($F{Soll}==null&&$F{Reste}==null))?"":"SUM(D"+(($V{PAGE_NUMBER}.intValue()*3)+$V{REPORT_COUNT}.intValue()+2)+",E"+(($V{PAGE_NUMBER}.intValue()*3)+$V{REPORT_COUNT}.intValue()+2)+")"

Elegant geht es auch so

($F{Zweckbestimmung}.isEmpty()||($F{Soll}==null&&$F{Reste}==null))?"":"INDIRECT(\"D\" & ROW())+INDIRECT(\"E\" & ROW())"

Das hat nur den Nachteil, dass die Formel in Excel nicht so schön ist.


==== WENN-/IF-Formel – '''Ein''' Fallstrick ====

Ein Fallstrick, der uns einige Stunden Arbeitzeit gekostet hat: die IF-Formel wird in OpenOffice und MS Excel mit dem Trennzeichen ";" für die THEN- und ELSE-Bedingung formuliert. JasperReports nutzt als Trennzeichen aber ",". Interessanterweise wird dann im fertigen Excel das "," als ";" angezeigt.


==== SUMIF – Summen mit Bedingungen (Bsp.: Zwischensummen ignorieren) ====

Wenn die Summe über einen großen Bereich gezogen werden soll, in dem auch Zwischensummen vorkommen, gibt es die Folgende Formel:

SUMIF(A"+$V{zeile_start}.intValue()+":A"+$V{zeile_ende}.intValue()+",\"<>Summe*\",B"+$V{zeile_start}.intValue()+":B"+$V{zeile_ende}.intValue()+")

Wenn die Zwischensummen mit addiert werden würden, wäre das Ergebnis doppelt so hoch wie es sein sollte. Die Funktion SUMIF beinhaltet 3 Bereiche. Zuerst wird der Bereich eingegeben, auf den die Bedingung angewendet wird:

A"+$V{zeile_start}.intValue()+":A"+$V{zeile_ende}.intValue()+"

Hier ist das z.B. von A1 bis A10.

Danach kommt die Bedingung:

\"<>Summe*\"

Das bedeutet, es werden alle Zeilen genommen, die '''''NICHT''''' mit „Summe“ anfangen.

Als letztes kommt der Bereich, der summiert werden soll:

B"+$V{zeile_start}.intValue()+":B"+$V{zeile_ende}.intValue()+"

Hier ist das z.B. von B1 bis B10.

In diesem Beispiel werden alle Zahlen zwischen B1 und B10 aufsummiert, wenn in der entsprechenden Zeile in der Spalte A der Text nicht mit „Summe“ beginnt.


==== Statt 0-Werten eine leere Zelle ausgeben ====

Im Standardfall wird eine 0 ausgegeben, falls eine Formel in Excel auf leere Zellen oder Zellen mit einer 0 verweist. Um stattdessen eine leere Zelle auszugeben wird die Property Property net.sf.jasperreports.export.xls.pattern genutzt. Das obige Beispiel wird erweitert:

###0.00;-###0.00;;@

Die jeweiligen Zellen weisen nun 2 Nachkommastellen aus und zudem werden 0-Werte nicht mehr angezeigt.


==== OpenOffice vs Excel ====

OpenOffice kommt mit folgender Berechnung klar

"INDIRECT(\"E\" & ROW())+INDIRECT(\"F\" & ROW())-INDIRECT(\"G\" & ROW())-INDIRECT(\"H\" & ROW())":""

Excel macht hier Ärger, wenn eine der Zellen Null ist, wird als Gesamtergebnis #WERT angezeigt, entweder Sum-Formel benutzen, oder noch mal mit IF prüfen, ob Zelle gefüllt ist

Struktur ist (IF(Zelle leer,0,sonst Zellenwert))

"IF(INDIRECT(\"E\" & ROW())=\"\",0,INDIRECT(\"E\" & ROW()))+IF(INDIRECT(\"F\" & ROW())=\"\",0,INDIRECT(\"F\" & ROW()))-IF(INDIRECT(\"G\" & ROW())=\"\",0,INDIRECT(\"G\" & ROW()))-IF(INDIRECT(\"H\" & ROW())=\"\",0,INDIRECT(\"H\" & ROW()))":""


=== ‚Stretch with Overflow‘ in Excel korrekt verarbeiten ===

Wenn Sie eine Zelle haben mit besonders langem Text, z.B. „Unterstützungen auf Grund der Unterstützungsgrundsätze, Fürsorgemaßnahmen sowie Kosten nach dem Arbeitssicherheitsgesetz“, hilft es, nur bei der Zelle, Line Spacing auf double zu setzen, dann sieht es in Excel besser aus.

Es wird das Stretch richtig verarbeitet.

<property name="net.sf.jasperreports.export.xls.auto.fit.row" value="true"/>

<property name="net.sf.jasperreports.export.xls.font.size.fix.enabled" value="true"/>

→ verkleinert fonts bei bedarf

<property name="net.sf.jasperreports.print.keep.full.text" value="true"/>


=== Pagination in Excel-Dokumenten ===

In Excel-Dokumenten in die Seitengröße naturgemäß irrelevant. Trotzdem wird das im jrxml gesetzte Seitenformat beim Excel-Export beachtet. Das stellt sich so dar, dass im Excel-Dokument der „Rest der Seite“ durch einzelne breitere beziehungsweise höhere Zellen gefüllt wird. Das sieht beispielsweise folgendermaßen aus:

[[Datei:JasperReports-Handbuch_excel_export_pagination1.png]]

Unter dem Tabellenschluss ist die Zeile 84 so hoch, dass die im jrxml eingestellte Seitenhöhe erreicht ist. Um das zu verhindern wird für den gesamten Bericht isIgnorePagination=“true“ gesetzt. Die Einstellung wird im source-Code ganz oben im Tag <jasperReport isIgnorePagination=“true“> gesetzt oder über die grafische Oberfläche:

[[Datei:JasperReports-Handbuch_excel_export_pagination2.png]]


=== Excel-Export in einzelne Tabellenblätter ===

Normalerweise werden beim Export nach Excel die Berichtsinhalte in das erste Tabellenblatt geschrieben. Je nachdem wie Sie auf Berichtsebene die Property net.sf.jasperreports.export.xls.one.page.per.sheet setzen, wird der Seitenumbruch gesteuert. Setzen Sie den Wert auf "true", dann führt jeder Seitenumbruch zu einem neuen Sheet bzw. Arbeitsblatt in der Excel-Datei. Standardmäßig werden diese dann "Page 1", Page 2" etc. benannt.

Wenn Sie die Namen der Sheets explizit vergeben wollen, können Sie dies wie folgt machen: Wenn Sie z.B. die Berichtsproperty net.sf.jasperreports.export.xls.sheet.names.all auf den Wert

"Hauptseite/wichtige Seite/Unwichtige Seite" setzen, bekommen Sie drei Sheets mit den jew. Namen, d.h. der "/" fungiert als Trennzeichen. Dementsprechend sollte im Namen des Sheets kein "/" auftauchen.

Seit JR 4.1 gibt es auch die Möglichkeit, die Sheetnamen dynamisch zu vergeben. Auch hier werden Properties mit Expressions genutzt.

Es gibt verschiedene Möglichkeiten Berichtsinhalte in verschiedene Excel-Tabellenblätter zu verteilen. Im Folgenden werden zunächst Möglichkeiten betrachtet, welche bei Einzelberichten in Frage kommen. Danach geht es um die klassische Haupt- und Unterberichtsstruktur und zuletzt um Booklets, welche die in den meisten Fällen wohl elegantere Alternative zu klassichen Haupt- und Unterberichten darstellen.


==== Einzelne Berichte ====

Nehmen wir an wir haben einen Bericht mit der Gruppierung auf die Spalte "LFB", im Gruppenkopf befindet sich ein Text Field mit der Expression $F{LFB}.

Sie können diesem Textfeld eine Property net.sf.jasperreports.export.xls.sheet.name geben:

[[Datei:JasperReports-Handbuch_excel_export_sheets_names.png]]

Das Textfeld erhält somit beim Füllen des Berichts den jew. Wert, z.B. "Anglistik, Amerikanistik", und diese Überschrift steht auch im Gruppenkopf. Wenn der Gruppenkopf das Attribut "Start on a new page" hat, dann beginnt der Gruppenkopf auf einer neuen Seite und, dank der Berichts-Property net.sf.jasperreports.export.xls.one.page.per.sheet , erzeugt Excel / OpenOffice dann ein neues Sheet mit dem Namen Anglistik, Amerikanistik. Beim Sheetnamen soll nur sichergestellt werden, dass kein "/" im Text vorkommt, daher der replace-Befehl zur Sicherheit. Hier ein Screenshot in OpenOffice:

[[Datei:JasperReports-Handbuch_excel_export_sheets_names2.png]]

Man kann das gesamte Verhalten auch deaktivieren, indem man auf Berichtsebene das Attribut "Ignore Pagination" auf "true" setzen. In diesem Falle werden alle Seitenumbrüche ignoriert.

<blockquote>Hinweis für SuperX/Edustore Nutzer: leider haben wir in älteren Kernmodul-Versionen dieses Attribut " Ignore Pagination" im Servlet fest auf "true" gesetzt, so dass Sie diese Funktion im Servlet erst ab Version SuperX 4.5 bzw. HISinOne-BI 7.0 nutzen können.
</blockquote>

==== Haupt- und Unterberichte ====

Das vorherige Kapitel hat aufgezeigt, wie innerhalb eines einzelnen Einzelberichtes mit gezieltem setzen von Seitenumbrüchen ein solcher Berichte auf verschiedene Tabellenblätter eines Excel-Dokumentes augeteilt wird.

Um mehrere Einzelberichte in einem Excel-Dokument gesondert auf verschiedene Tabellenblätter aufzuteilen eignen sich klassiche Haupt- und Unterberichtsstrukturen (vgl. Kapitel 3.5). Die simpelste Methode wäre das Seitenlayout eines Berichtes so groß zu wählen, dass der gesamte Bericht auf eine Seite passt.

Falls Haupt- und Unterberichte verwendet werden, darauf achten, dass der Hauptbericht direkt unter dem letzten Unterberichtselement endet. Ansonsten entsteht ein weiteres leeres Tabellenblatt. Der folgende Screenshot zeigt, wie es nicht sein sollte. Hier muss das Summary-Band verkleinert werden, sodass es mit dem Unterberichtselement endet.

[[Datei:JasperReports-Handbuch_excel_export_main-_subreport.png]]


==== '''Individuelle Gestaltung''' bei Booklets ====

Booklets bieten diverse Vorteile beim Gestalten der einzelnen Seiten beziehungsweise Sheets. Denn jeder Unterbericht kann hier individuell formatiert werden. Dies betrifft beispielsweise die Definition von Sheetnamen, da hierfür die Eigenschaft "Tab name expression" im "Buch"-[[#2.8.1.Hauptbericht im Booklet|outline|Bericht]] vorgesehen ist. Auch das Problem, dass ein Sheet in diesem Falle nicht mehrere Seite umfassen darf (und man somit die Seitengröße unrealistisch groß machen muss) ist damit behoben.

Eine Ausnahme stellen jedoch die Properties dar. Diese werden im Hauptbericht gesetzt und gelten für alle Unterberichte.


=== Das Drucklayout in Excel konfigurieren ===


==== '''Seitenränder und Kopfzeile im Drucklayout formatieren''' ====

Zum Anlegen eines Textes in der Kopfzeile gibt es die Properties

<property name="net.sf.jasperreports.export.xls.sheet.header.center">

<property name="net.sf.jasperreports.export.xls.sheet.header.right">

<property name="net.sf.jasperreports.export.xls.sheet.header.left">

Je nach gewünschter Position wird der jeweiligen Property ein Wert übergeben. Ein Beispiel:

<property name="net.sf.jasperreports.export.xls.sheet.header.center">

<![CDATA[&"Liberation Sans,Bold"&10Meldung der Ist-Besetzung]]>

</property>

<property name="net.sf.jasperreports.export.xls.sheet.header.right">

<![CDATA[&"Liberation Sans,Bold"&10Anlage 1 &"Liberation Sans,Regular"&10 (zu VwV HWiF 3.2.1)]]>

</property>

In diesem Beispiel wird zentral der Text „'''Meldung der Ist-Besetzung'''“ übergeben. Der Text ist in der Schriftart Liberation Sans und fettgedruckt formatiert (&"Liberation Sans,Bold"), sowie in Schriftgröße 10 (&10).

Rechts wird der Text „'''Anlage 1 '''(zu VwV HwiF 3.2.1)“ verwandt. Der erste Teile „'''Anlage 1'''“ ist wie der zentrale Text formatiert (&"Liberation Sans,Bold"&10). Für den zweiten Teil „(zu VwV HwiF 3.2.1)“ wird von Fett- auf Regulärdruck gewechselt (&"Liberation Sans,Regular"&10). Weitere Möglichkeiten zur Formatierung finden sich auf https://poi.apache.org/apidocs/dev/org/apache/poi/xssf/usermodel/extensions/XSSFHeaderFooter.html.

Damit die Kopfzeile im Drucklayout sichtbar ist, ist es notwendig den Seitenrand groß genug zu gestalten. Dafür werden folgende Properties genutzt:

<property name="net.sf.jasperreports.export.xls.print.page.left.margin" value="20"/>

<property name="net.sf.jasperreports.export.xls.print.page.right.margin" value="20"/>

<property name="net.sf.jasperreports.export.xls.print.page.top.margin" value="40"/>

<property name="net.sf.jasperreports.export.xls.print.page.bottom.margin" value="10"/>


==== Vordefinierte Zeilen im Drucklayout auf jeder Seite wiederholen ====

Um im Drucklayout beispielsweise einen Tabellenkopf auf jeder Seite zu wiederholen, wird die Property

<property name="net.sf.jasperreports.export.xls.sx_repeating.rows.range" value="3:7"/>

genutzt (dafür eigene Klasse de.superx.servlet.SxJRXlsExporter geschaffen und de.superx.servlet.JasperCreator angepasst – aktuell in NHS-Pack für 7.1 enthalten). Der Wert gibt an, welche Zeilen des Excel-Dokumentes im Drucklayout auf jeder Seite wiederholt werden. Im Beispiel (''value="3:7"'') sind die Zeilen 3 bis 7 betroffen.


==== Seitenumbrüche im Drucklayout verhindern ====

Teilweise ist es wünschenswert Seitenumbrüche im Drucklayout zu verhindern, sowohl in der Breite als auch in der Höhe. Hierfür werden die Properties

<property name="net.sf.jasperreports.export.xls.fit.width" value="1"/>

<property name="net.sf.jasperreports.export.xls.fit.height" value="1"/>

genutzt. Also value kommen hier 1 und 0 für entweder true oder false infrage. Setzt man der Wert true, dann wird nicht umgebrochen. Das bedeutet für dieses Beispiel, dass der gesamte Inhalt des Excel-Dokuments auf eine Seite gedruckt würde.


=== Zellen verbinden ===

<property name="net.sf.jasperreports.export.xls.export.xls.sx_cell_merge" value="0,6,0,7|1,2,3,4"/>

1,1,4,1 - will merge from B2 to E2. Remember it is zero based indexing.


=== Zellschutz aktivieren ===

<property name="net.sf.jasperreports.export.xls.password" value="gmmmyflb"/>

→ Alle Zellen sind mit Passwort geschützt.

Wenn bestimmte Spalten/Zeilen nicht geschützt sein sollen:

Property net.sf.jasperreports.export.xls.cell.locked false.

Dies kann man auch über eine komplexe PropertyExpression steuern, z.B.

(

($F{Zeile}!=null&&(

$F{Zeile}.indexOf("A")>-1||

$F{Zeile}.indexOf("B")>-1||

$F{Zeile}.indexOf("C")>-1||

$F{Zeile}.equals("I.")||

$F{Zeile}.equals("II.")||

$F{Zeile}.equals("III.")||

$F{Zeile}.equals("IV.")||

$F{Zeile}.equals("V.")||

$F{Zeile}.equals("VI.")||

$F{Zeile}.equals("VII.")||

$F{Zeile}.equals("VIII.")))||

($F{Kontengruppe}!=null&&$F{Kontengruppe}.equals("53,54,58"))||

($F{Name}!=null&&(

$F{Name}.startsWith("= Summe der (ordentlichen")||

$F{Name}.startsWith("Ordentliche ")||

$F{Name}.startsWith("- ordentliche")||

$F{Name}.startsWith("+/- Finanz")||

$F{Name}.startsWith("Summe Investitionen")||

$F{Name}.startsWith("Summe Finanzbedarf")||

$F{Name}.startsWith("Summe Deckung")||

$F{Name}.startsWith("5.1 E")||

$F{Name}.startsWith("Summe sonstige betriebl")||

$F{Name}.startsWith("Sonstige betriebliche")||

$F{Name}.startsWith("5.1.) Erträge aus Zuweisungen")||

$F{Name}.startsWith("Materialaufwand")||

$F{Name}.startsWith("= Summe Materialaufwand")||

$F{Name}.startsWith("Personalaufwand")||

$F{Name}.startsWith("= Summe Personalaufwand")||

$F{Name}.startsWith("Sonstige betriebliche Aufwendungen")||

$F{Name}.startsWith("= Summe sonstige betriebliche Aufwendungen")

)

))?"true":"false"


=== Zellen fixieren ===

In Jaspersoft Studio können Sie festlegen, dass beim Excel-Export bestimmte Zeilen und Spalten fixiert werden, indem Sie spezielle Eigenschaften für den Export konfigurieren.

Um Zeilen und Spalten in Excel zu fixieren, müssen Sie die Eigenschaften

''net.sf.jasperreports.export.xls.freeze.row ''

und

''net.sf.jasperreports.export.xls.freeze.column''

konfigurieren.

Wenn Sie möchten, dass die erste Zeile und die erste Spalte fixiert werden:

* ''net.sf.jasperreports.export.xls.freeze.row = 2''
* ''net.sf.jasperreports.export.xls.freeze.column = B''

Nach dem Export werden in Excel die erste Zeile und die erste Spalte fixiert, und der Rest des Arbeitsblatts bleibt scrollbar.

''<property name="net.sf.jasperreports.export.xls.freeze.column" value="B"/>''

<property name="net.sf.jasperreports.export.xls.freeze.row" value="2"/>


=== Hintergrund- oder Textfarben beim Excel-Export ===

Beim Excel Export werden Zellen, die ein Rechteck mit einer Print-When-Expression zugewiesen bekommen haben, u.U. nicht richtig wiedergegeben, während es beim PDF Export klappt. Um dies zu beheben müssen Sie

1. den Farbraum beim Excel Export erweitern: Excel unterstützt bei Hintergrund- oder Vordergrundfarben nur wenige [http://dmcritchie.mvps.org/excel/colors.htm Farbcodes]. Für spezielle Farben nach RGB-Wert muss die Berichts-property

<property name="net.sf.jasperreports.export.xls.create.custom.palette" value="true"/>

gesetzet werden (benötigt Bibliothek org-netbeans-core.jar im Classpath der Anwendung)

2. Statt farbiger Textfelder oder Rechtecke mit "Print-When-Expression" müssen Sie [[#2.11.Conditional styles - Zeilen fett machen|outline|Conditional Styles]] nutzen.

3. Wenn Sie mit Hintergrundfarben arbeiten, müssen die Textfelder und die jew. Styles die Eigenschaft "Opaque"="true" haben.

4. Beim Export nach Excel müssen Sie das JExcelApi nutzen. Dies ist bei SuperX seit Kernmodul 4.5 der Standard, bei HISinOne-BI seit Version 7.1.


=== Seitenkopf und Seitenfuß bei Excel unterdrücken ===

Wenn Ihr Bericht normalerweise ein Band "Page Header" bzw. "Page Footer" hat, können Sie dies beim Exportformat XLS unterdrücken (z.B. wenn Sie dort keine Seitenzahlen wünschen, bei PDF aber schon).

Setzen Sie dazu die Berichts-Property

<property name="net.sf.jasperreports.export.xls.exclude.origin.band.1" value="pageHeader"/>

<property name="net.sf.jasperreports.export.xls.exclude.origin.band.2" value="pageFooter"/>

Beim Ausgabeformat XLSX heißen die Properties:

<property name="net.sf.jasperreports.export.xlsx.exclude.origin.band.1" value="pageHeader"/>

<property name="net.sf.jasperreports.export.xlsx.exclude.origin.band.2" value="pageFooter"/>

Dies klappt ab JR Version 4.5, sie können diese Properties aber lediglich im XML-Quellcode hinzufügen.


== Dimension Tausend-Euro ==

In Excel als Dimension Tausend-Euro ausgeben, mit zwei Nachkommastellen

In Deutschem Excel bei manueller Angabe benutzerdefiniertes Format #.##0,00.

In Jasper muss Amerikanische Vorlage sein:

-> #,##0.00

Bei Excel kann man als Property Expresion net.sf.jasperreports.export.xls.pattern z.B. nehmen

#, → zeigt nur Tausender Werte an

#,##0.00, → zeigt Tausernder Werte, mit zwei Nachkommastellen an

der Werte selber ist einfach $F{Soll}

Bei PDF/HTML muss man den Wert duch 1000 teilen $F{Soll}.doubleValue()/1000

und dann als Pattern z.B. #,##0.00;-#,##0.00

Die Rundung macht das Pattern.


= Nutzung in Edustore =


== Berichtsentwicklung bei Grunddaten und Basisberichten ==


=== Allgemein ===

In den Grunddaten- und Basisberichten kann man beliebige Ergebnistabellen lokal als XML speichern, und dann als Datenquelle in JasperReports einbinden. Dann kann man den Bericht lokal gestalten, und, wenn er fertig ist, in die Weboberfläche einhängen. Die XML Datei wird nur für die Testausgabe bei JasperReports verwendet und dient als Ersatz der Datenbank. Wenn der Bericht in der Weboberfläche eingehängt ist, wird dieser direkt mit frischen Daten versorgt.

Für die Folgenden 2 Punkte „Datenquelle erzeugen“ und „Template erzeugen“ gibt es [http://www.superx-projekt.de/doku/benutzerhandbuch/movies/jasper_erzeugen.viewlet/jasper_erzeugen_viewlet_swf.html hier] einen Kurzfilm.

[[Datei:JasperReports-Handbuch_vergleich_jrxml_xml_zusammen.png]]


=== Datenquelle erzeugen ===

Wenn die Ergebnistabelle eines Berichtes vorliegt, erhält man über den XML Export von SuperX die Datenquelle für den Jasper Report.

[[Datei:JasperReports-Handbuch_iReport-Datasource_erstellen.jpg]]

Diese Datei speichert man lokal ab: Wenn das Ergebnis im Browser geöffnet wurde muss man sich den Quelltext der Seite anzeigen lassen, den Quelltext komplett markieren und kopieren ( Tastenkombination Strg + a und dann Strg + c), in einen UTF-8-fähigen Texteditor einfügen (Strg + v) und dann als eine xml-Datei abspeichern.

Falls der Tomcat in ISO Kodierung läuft, muss für JasperReports in der ersten Zeile bei encoding ein UTF-8 eingetragen werden.

Beispiel:

<?xml version="1.0" encoding="ISO-8859-1"?>

wird ersetzt mit:

<?xml version="1.0" encoding="UTF-8"?>

In JasperReports sind dann folgende Schritte zu tun, um die neue Datenquelle einzubinden.


==== Datenquelle in JasperSoft Studio ====

Die Datenquellen heißen hier "Data Adapters" und werden im Repository hinzugefügt:

[[Datei:JasperReports-Handbuch_jaspersoft_datasource1.png]]

<blockquote>Achtung: wenn Sie JasperSoft in Ihrem vorhandenen Eclipse als Plugin installiert haben, sehen Sie den Reiter "Repository" nicht; in diesem Fall liegen die Data Adapter im jew. Projekt.
</blockquote>
Im Assistenten geben Sie XML-Document als Datentyp an, und im nächsten Reiter spezifizieren Sie das Format:

[[Datei:JasperReports-Handbuch_jaspersoft_datasource2.png]]

Das Datumsformat ist bei Edustore das deutsche Schema "dd.MM.yyyy", und das Zahlenformat ist eine Zahl mit 6 Nachkommastellen und "." als Dezimaltrenner, also "#0.######". Bei Locale müssen Sie "Englisch" angeben, weil Dezimalzahlen in den Edustore-XML-Quellen den "." als Dezimaltrenner haben.

Wichtig ist auch das Ankreuzfeld "Use the report Xpath expression", dies müssen Sie immer ankreuzen.


==== Datenquelle in iReport ====

Klick auf „Report Datasources“. Es öffnet sich ein Fenster, in dem die vorhandenen Datenquellen angezeigt werden.

[[Datei:JasperReports-Handbuch_iReport-Datasource_1.jpg]]

In diesem Fenster Klickt man auf „New“ um eine neue Datenquelle anzulegen.

[[Datei:JasperReports-Handbuch_iReport-Datasource_2.jpg]]

Nun wählt man „XML file datasource“ aus und klickt auf „Weiter“.

[[Datei:JasperReports-Handbuch_iReport-Datasource_3.jpg]]

Im letzten Schritt wählt man einen Eindeutigen Namen aus, der auch später in dem Dropdown Menü erscheint, gibt den Dateipfad an und ändert die restlichen Einstellungen wie im Screenshot.

[[Datei:JasperReports-Handbuch_iReport-Datasource_4.jpg]]

Die Formate für Datum und Nummer müssen angegeben werden, da sonst die amerikanischen angenommen werden. Bei Locale müssen Sie "Englisch" angeben, weil Dezimalzahlen in den Edustore-XML-Quellen den "." als Dezimaltrenner haben.

<blockquote>Hinweis: in JasperReports 3.7.1 werden trotz des korrekten Zahlenformats die Dezimalstellen von Beträgen immer mit ",00" wiedergegeben. Dies liegt an der "Locale", man muss diese auf "Englisch" umstellen. Das Problem ist allerdings: sobald man das macht, kann man die XML-Datenquelle in der Datenquellenverwaltung nicht mehr ändern, d.h. man muss sie bei Änderungen löschen und neu einfügen.
</blockquote>
Nach dem Speichern erscheint die Datenquelle im dropdown Menü und kann ausgewählt werden. Damit man die Datenquelle nutzen kann, braucht man auch noch ein Template.


=== Template erzeugen ===

Um ein leeres Template zu erzeugen, geht man wieder in die Ergebnistabelle der selben Maske, deren Datenquelle erstellt wurde, wählt im Dropdown Menü neben „Bericht entwerfen“ „Leerer Bericht“ aus und klickt auf das Icon daneben „Export als JasperReport-Template“.

[[Datei:JasperReports-Handbuch_iReport-leeren_Bericht_erstellen.jpg]]

Diese Datei speichert man Lokal ab. Wenn das Ergebnis im Browser geöffnet wurde muss man sich den Quelltext der Seite anzeigen lassen, den Quelltext komplett markieren und kopieren ( Tastenkombination Strg + a und dann Strg + c), in einen UTF-8-fähigen Texteditor einfügen (Strg + v) und dann als eine jrxml Datei abspeichern. JR in der Endung jrxml steht für JasperReports. Damit können die Datenquellen und die Templates unterschieden werden und sogar den selben Dateinamen tragen (nur unterschiedliche Dateiendung).

Sie sollten es sich nicht zumuten und versuchen über JasperReports einen neuen Bericht zu entwerfen. Nehmen Sie immer den "leeren" Bericht aus der entsprechende Maske, da dort sehr viele Kleinigkeiten voreingestellt sind. Sie sparen sich damit immens viel Arbeit.


=== Template einbinden ===


==== Reportdesign verlinken ====

Um das erstellte Template einzubinden, muss zunächst die jrxml Datei in das Verzeichnis webapps/superx/WEB-INF/reports kopiert werden. Danach muss das Stylesheet im System bekannt gegeben werden. In Grunddaten und Basisberichte geht man dazu in „Administration“ → „Masken“ → „Stylesheet suchen“ und schickt die Maske so ab. Danach klickt man bei einem beliebigen Stylesheet auf den „bearbeiten“ Button ganz rechts in der Tabelle.

[[Datei:JasperReports-Handbuch_iReport-Stylesheet_1.jpg]]

Klickt dann auf „Neuen Datensatz erzeugen“.

[[Datei:JasperReports-Handbuch_iReport-Stylesheet_2.jpg]]

In Dateiname kommt der Dateiname der jrxml Datei rein, welche sich in dem reports Ordner befindet. Beschriftung und Beschreibung sollte eindeutig dem Stylesheet zuzuordnen sein. Für JasperReport wählt man bei „Tabelle oder Maske“ „Stylesheet für eine Ergebnistabelle“ aus. Der Dateityp stellt das default Ausgabeformat fest.

Um dieses Stylesheet nun einer Maske zuzuordnen, geht man in die Maske „Administration“ → „Masken“ → „Maske suchen“, sucht in dem Feld „Maske“ die gewünschte Maske aus und klickt dann auf „Abschicken“. Nun klickt man auf den Button Stylesheets neben der Maske, der das neue Stylesheet zugeordnet werden soll.

[[Datei:JasperReports-Handbuch_iReport-Stylesheet_3.jpg]]

In dem neuen Fenster wählt man das neu erstellte Stylesheet aus und speichert diese Einstellung ab.

[[Datei:JasperReports-Handbuch_iReport-Stylesheet_4.jpg]]

Damit ist der Bericht der Maske zugeordnet.

<blockquote>Normal wird im Servlet direkt vom Berichtsergebnis nach JasperReports übergeben, d.h. ohne den Zwischenweg XML. Wenn aber im Dateinamen *_xmlsource.jrxml steht, wird Datenquelle XML erzwungen (für Makroberichte, Unterberichte, Subdatasets oder spezielle XPATH-Selektionen wichtig).
</blockquote>

==== Nutzung des Upload Servlets ====

Wenn Sie keinen Schreibzugriff auf den Ordner ''WEB-INF/reports'' haben, können Sie auch Templates über das [http://www.superx-projekt.de/doku/kern_modul/admin/f_Anpassungderwebxml.htm Upload Servlet ]direkt im Browser hochladen. Dazu müssen Sie in der web.xml die Dateiendungen .jrxml und (sofern benötigt) .jasper erlauben, siehe obiger Link.

Danach können Sie die Report Templates hochladen:

[[Datei:JasperReports-Handbuch_jr_upload1.png]]

Nach dem Upload können Sie das Template zunächst registrieren:

[[Datei:JasperReports-Handbuch_jr_upload2.png]]

und dann der jew. Maske zuordnen. Beachten Sie, dass der Pfadname relativ zum Ordner WEB-INF/reports angegeben wird, also in der Regel

../../default/custom

bzw. beim Mandantenbetrieb

../../Mandant-ID/custom


==== Probleme beim Deployment im Server ====

Es kann u.U. beim Deployment eines Berichts im Server das Problem auftreten, daß ein Bericht im lokalen iReport mit der XML-Datenquelle funktioniert, aber im Server für einzelne Merkmale kein Ergebnis geliefert wird. Dies hat folgende Ursache:


===== Feldnamen im Berichtsdesign weichen vom Datenbank-Feldnamen ab =====

Bei der lokalen Entwicklung in iReport werden die Berichte mit der Datenquelle XML erzeugt. In den Muster-JRXML-Dateien, die man über das Feld "Bericht erzeugen" generiert, sind die Felder über die folgende Notation deklariert:

<field name="Fakultät/Fachbereich (Schlüssel)" class="java.lang.String">

<fieldDescription><![CDATA[col[@id="4" and wert!=""]/wert]]></fieldDescription>

</field>

Dies bedeutet: Das Feld "Fakultät/Fachbereich (Schlüssel)" hat den Typ "String" und befindet sich im XML-Datenstrom in der vierten Spalte (col@id=4). Dabei befindet sich in Datenblattberichten im Spaltennamen immer ein "\n" vor der Zeichenkette "(Schlüssel)", um einen Zeilenumbruch im generischen Standardlayout zu erzeugen. Dieses "\n" wird dann für iReport und JasperReports automatisch durch ein Leerzeichen ersetzt.

Wenn die XML-Datenquelle nicht verändert wird, dann ist das Feld immer mit dem gleichen Inhalt gefüllt.

Wenn man den Bericht dann auf den Server kopiert und einbindet, ohne im Dateinamen "_xmlsource" zu verwenden, dann wird das Feld nicht über die Spaltennummer identifiziert, sondern über den Feldnamen, hier z.B. "Fakultät/Fachbereich (Schlüssel)". Das bedeutet, daß der Server genau diesen Feldnamen zurückliefern muss. Das kann u.U. abweichen:

* Der Server bzw. die zugrunde liegende Maske wurde verändert, so daß der Feldname geringfügig anders ist. Das sollte eigentlich nicht passieren, kann aber vorkommen.
* Beim Betrieb in HISinOne gibt es in allen Versionen bis 3.02 noch eine kleine Veränderung, wenn das Modul des zugrunde liegenden Datenblattberichts bzw. der Maske direkt per Tomcat-Start installiert wurde, und nicht in dem Edustore-Installation/Upgrade-Menü. Wenn die Module beim Tomcat Start in eine leere Datenbank installiert werden, dann werden Zeichenketten mit dem Feldinhalt "\n" verfremdet nach "n" (also der "\" wird entfernt). Das führt dann dazu, daß das Feld ohne den "\" in der jrxml-Datei deklariert wird, also z.B.

<field name="Fakultät/Fachbereichn(Schlüssel)" class="java.lang.String">

<fieldDescription><![CDATA[col[@id="4" and wert!=""]/wert]]></fieldDescription>

</field>

Wenn man danach dann einen Upgrade der jew. Komponente ausführt, dann wird die Spalte in der Maske umbenannt nach "Fakultät/Fachbereich'''\n'''(Schlüssel)" und der Feldname korrekt nach "Fakultät/Fachbereich''' '''(Schlüssel)" umgesetzt. Durch das "n" vor der Zeichenkette "(Schlüssel)" paßt der Feldname in der jrxml-Datei nicht mehr zum Ergebnis aus der Datenbank, und das Feld ist leer. So kann es passieren, daß ein Bericht in iReport funktioniert, im Server aber nicht. Im folgenden die Lösung.


===== Korrektur der Feldnamen im Berichtsdesign =====

Um sicherzustellen, dass der Feldname der jrxml-Datei mit der jeweils aktuell benutzten Datenbank-Version übereinstimmt, geht man wie folgt vor:

* Erzeugen Sie in Edustore eine HTML-Ausgabe der zugrunde liegenden Abfrage, bei Datenblatt-Berichten ist dies das "generische Standardlayout".
* Klicken Sie dann oben im Berichtskopf auf den Button "Bericht entwerfen" -> "leerer Bericht"
* Im Quellcode sehen Sie die Zeilen <field name="Berichtsname" class="java.lang.String"> ... Hier ist jedes einzelne Feld aus der Datenbank deklariert.
* Markieren Sie alle Zeilen bis zum letzten "<field...>"-Element, i.d.R. ist dies das Feld <field name="user"..., und kopieren Sie dies in die Zwischenablage
* Öffnen Sie die jrxml-Datei mit einem UTF-8-fähigen Editor, z.B. Jedit.
* Ersetzen Sie genau die "<field..."-Passage aus der Zwischenablage.
* Speichern Sie den Bericht, und testen Sie die Vorschau in JasperReports. Wahrscheinlich kommt eine Fehlermeldung "Field ... does not exist" o.ä., dann müssen Sie das Feld mit Suchen->Ersetzen umbenennen.
* Das machen Sie so lange, bis die Vorschau funktioniert. Danach können Sie die jrxml-Datei wieder auf den Server kopieren. Die Felddeklaration passt dann zum Server.


== Zuordnung von Default-Feldbelegungen zu Stylesheets ==

Es können für Stylesheets Default-Feldbelegungen für Stylesheets hinterlegt werden. Hintergrund dieser Funktion ist, dass bei speziellen Stylesheets standardmäßig beliebig viele Spalten vorbelegt werden können. In Datenblattberichten gibt es z.B. das Feld "Felder", in dem die auszugebenden Spalten angegeben werden. Aus Performancegründen sollten nur die Spalten ausgegeben werden, die auch benötigt werden. So kann dann z.B.für JasperReport Stylesheets hinterlegt werden können, welche Spalten auf jeden Fall benötigt werden. Der Anwender weiß nicht welche Spalten benötigt werden und würde im Normalfall alle Spalten ausgeben lassen um keine Fehlermeldung zu erhalten. Dadurch würde aber wiederum der Bericht unnötig lange dauern, da alle Spalten berechnet werden müssen, auch die, welche nicht benötigt werden.

Wenn Sie ein Stylesheet erstellt haben und dieses in SuperX eingebunden haben gehen Sie wie folgt vor:

Sie gehen in die Maske "Administration -> Tabelle suchen", geben dort bei Stichwort "stylesheet_field" ein und schicken die Maske ab.

[[Datei:JasperReports-Handbuch_stylesheet_field_maske.png]]

In der folgenden Ergebnistabelle klicken Sie bei "stylesheet_field_list" auf den "Bearbeiten" Button.

[[Datei:JasperReports-Handbuch_stylesheet_field_tabelle.png]]

In dem nun geöffneten Fenster sehen Sie alle Zuordnungen, welche bereits eingetragen sind. Hier wird aber lediglich das Stylesheet ausgegeben und nicht die Tabellen und Federzugehörigkeit. Dies hätte wegen der vielen Auswahlmöglichkeiten jeden Browser gekillt. Um Einzelheiten zu erfahren müssen Sie daher auf den Details-Button klicken. Auch wenn Sie eine neue Zuordnung erstellen möchten klicken Sie zunächst auf den Detail-Button eines beliebigen Stylesheets.

[[Datei:JasperReports-Handbuch_stylesheet_field_list.png]]

Jetzt können Sie die Zugehörigkeit des Stylesheets zu Tabelle und Feld ändern oder eine neue Zuordnung erstellen.

Achtung: Wenn ein Tabellenname ausgewählt und abgespeichert wurde, können nur Spalten dieser Tabelle ausgewählt werden. Wenn Sie die Tabelle ändern wollen, müssten Sie zunächst die Tabelle ändern, abspeichern und dieses Formular erneut aufrufen. Erst dann würden die Spalten der ausgewählten Tabelle in der Listbox Fieldname erscheinen.

[[Datei:JasperReports-Handbuch_stylesheet_field_edit.png]]

Um eine neue Verknüpfung zu erstellen klicken Sie zuerst auf den + Button oben rechts. Danach erscheint das gleiche Formular nur ohne ausgefüllte Felder. Hier können Sie das Stylesheet und den Tabellennamen auswählen und die dazu passende Spalte der Tabelle die Sie zuvor ausgewählt haben. Achten Sie darauf die Tabelle zu nehmen, welche im Datenblatt verwendet wird. Danach nur noch über das Diskettensymbol oben rechts abspeichern und eine Spalten-Stylesheet-Verknüpfung ist fertig. Diesen Schritt wiederholen Sie für jede Spalte, die Sie in dem JasperReport Bericht benötigen.

Ab Kernmodul 4.2 bzw. HISinOne 5.1 geht es noch komfortabler, Sie können hier auf einzelne Stylesheets filtern : Administration → Masken → Stylesheet suchen

Wählen Sie zunächst den Bericht aus, und klicken Sie dann rechts beim Bearbeiten-Button in der Spalte Felder-Vorbelegungen bearbeiten:

[[Datei:JasperReports-Handbuch_stylesheet_field.png]]

In dem Bearbeitungsformular können Sie Datensätze erzeuge, löschen etc.


== Kurzanleitung Direktaufruf von Jasper-Berichten von der Maske ==

Nach dem Abschicken der Maske kann man auch direkt auf den entsprechenden Jasper-Bericht umgeleitet werden. Es muss dazu in der Maske ein Feld geben mit dem Namen

tablestylesheet

und der relation

<<SQL>> select distinct filename,X.caption from sx_stylesheetsX, 
sx_mask_style S where X.tid=S.stylesheet_id and S.maskeninfo_id=23880

und zum Beispiel für Default der Maske 23880

<<SQL>> select distinct filename,X.caption from sx_stylesheets X,sx_mask_style S where X.tid=S.stylesheet_id and S.maskeninfo_id=23880 and S.ord=2

Für die Anzeige des Feldes tablestylesheet im Browser wird eine Berschriftung caption hinterlegt, damit auf der Maske "Bericht" erscheint. Im neuen Kern-Modul passiert dies automatisch.

Es ist möglich einen manuellen Eintrag in die Tabelle ''sx_captions'' einzufügen (siehe Maske Administration -> Maske -> Beschriftung suchen).

{| class="wikitable"
|-
!
!
!
!
!
|-
| tid
| table_name
| field_name
| locale
| contents_short
|-
| <<wird automat. vergeben>>
| felderinfo
| tablestylesheet
| de
| Bericht
|}

Außerdem muss man die Maske um ein Feld Ausgabeformat ergänzen, das die Art=1 hat und folgende relation:

select element_value,description from menu_element where element='Ausgabeformat' and nature::smallint<100 order by nature::smallint

Beispiel für Default Excel:

<<SQL>> select element_value,description from menu_element where element='Ausgabeformat' and description='Excel'

Achtung: Hier kommen erst Ergebnisse, wenn Sie das Kernmodul 4.1 / HISinOne 3.0 oder höher installieren.


== Spezielle Variablen ==

Im Berichtsdesign können neben den Feldern der Ergebnistabelle auch z.B. der Berichtsname, Erleuterung, user und standdatum benutzt werden. Zu finden sind diese im "Report Inspector" unter Fields. Um auch Hochschulspezifische Informationen wie Hochschulname oder Hochschul-Webadresse in einen Bericht importieren zu können wurden unter anderem die sx_captions Variablen "REPORT_HEADING_INSTITUTION" und "REPORT_HEADING_URL" integriert.

[[Datei:JasperReports-Handbuch_sx_captions_markiert.png]]

Diese können genau wie die anderen Fields in den Bericht per Drag&Drop gezogen werden.


== Makroberichte als Datenquelle für JasperReports ==

Sie können als Datenquelle für JR nicht nur einzelne Masken nehmen, sondern auch die Ausgabe von Makro-Masken. Dadurch können die verschiedenartigsten Informationen aus den normalen Masken für übergreifende Berichte genutzt werden.

Das folgende Beispiel zeigt, wie im KLR-Bericht "Berichtsblatt: Kennzahlen aus der Kostenrechnung" Teile verwendet werden, um einen eigenen JR zu erzeugen, der wiederum Elemente des Makroberichts als Unterbericht nutzt.

Zunächst rufen Sie den Makrobericht auf:

[[Datei:JasperReports-Handbuch_makro_html.png]]

Das Bild zeigt die ersten drei Elemente des Makros, sie werden mit einer Ordnungsnummer durchnummeriert.

Wir laden dazu die XML-Datenquelle herunter, die XML-Datenquelle binden wir wie [[#3.1.2.Datenquelle erzeugen|outline|gewohnt]] in JasperReports ein:

[[Datei:JasperReports-Handbuch_makro_datenquelle.png]]

Dann klicken wir im Browser über den Tabellen den Button rechts von "Bericht entwerfen" → Leerer Bericht. Die JRXML-Datei speichern wir wie [[#3.1.3.Template erzeugen|outline|gewohnt]].

Im Designer sehen wir nun bei den Feldern eine erweiterte Liste:

[[Datei:JasperReports-Handbuch_makro_jrxml.png]]

Wir sehen also, daß die Ergebnisspalten mit einem Präfix für die Tabellennummer versehen sind, z.B. "tab_0". Dadurch können wir die Tabellen und somit auch die jew. Spalten eindeutig identifizieren. Dies ist gleichzeitig der Hauptbericht. Das Detail-Band löschen wir (ist nicht nutzbar), stattdessen aktivieren wir ein Summary Band.

Dann erzeugen wir den [[#2.5.Unterberichte |outline|Unterbericht]] für Studierenden-VZÄ. Dazu speichern wir die obige jrxml-Datei z.B. mit dem Namen makro_beispiel_ub_stud.jrxml und entfernen das Titel-Band und Seitenfuß-Band. Dann fügen wir im Designer einen Parameter "ordnr" hinzu:

[[Datei:JasperReports-Handbuch_makro_ub_param.png]]

Der Unterbericht bekommt dann in der Report Query folgende Änderung:

[[Datei:JasperReports-Handbuch_makro_ub_report_query.png]]

Die Ordnungsnummer wird vom Hauptbericht übergeben und dient dazu, in der XML-Datenquelle auf die einzelne Tabelle zu filtern.

Zusätzlich geben wir noch einen weiteren Filter ein, damit die Summenzeilen aus der Originaltabelle nicht in die Kreuztabelle aufgenommen werden:

[[Datei:JasperReports-Handbuch_makro_ub_filter.png]]

Damit der Unterbericht auch "stand-alone" ausführbar ist, können Sie dem Parameter "ordnr" auch einen Standardwert zuweisen, hier z.B. "2":

[[Datei:JasperReports-Handbuch_makro_ub_ordnr_default.png]]

Nun können wir die [[#2.5.Unterberichte |outline|Kreuztabelle]] mit dem Assistenten erzeugen. Für unser Beispiel enthält die Kreuztabelle Studierenden-VZÄ nach Studiengang und Fachkennzeichen:

[[Datei:JasperReports-Handbuch_makro_ub_crosstab.png]]

Wir speichern den Unterbericht und binden ihn in den Hauptbericht im Summary Band ein. Dabei vergeben wir wie gewohnt die Parameter XML_LOCALE und XML_NUMBER_PATTERN. Außerdem erzeugen wir den Parameter "ordnr", und weisen diesem den Wert 2 zu, weil die Studierenden-Tabelle die Ordnungsnummer 2 hat (s.o.):

[[Datei:JasperReports-Handbuch_makro_hauptbericht_ub_params.png]]

Damit ist die Konfiguration beendet, der Bericht sieht so aus:

[[Datei:JasperReports-Handbuch_makro_hb_erg.png]]

Weitere Unterberichte lassen sich analog hinzufügen.

<blockquote>Hinweis zum Einbinden im Servlet: Unterberichte arbeiten nur mit der Datenquelle XML, daher müssen Sie die Datei des Hauptberichts mit dem Suffix "_xmlsource" versehen.
</blockquote>


== Kompatibilität von iReport mit JasperReports ==

Wenn Sie mit iReport Berichte erzeugen, sollte wie gesagt die iReport-Versionsnr. mit der JasperReports-Version übereinstimmen, die der jew. Server nutzt. In Edustore ist dies derzeit die Version 5.1.0. Wenn die Versionsnummern nicht übereinstimmen, dürfen Sie keinesfalls die *.jasper-Dateien von dem lokalen Arbeitsplatz zum Tomcat Server kopieren.

Darüber hinaus kann es auch weitere Abhängigkeiten geben, iReport bringt ein paar mehr Bibliotheken mit, als JasperReports. Wenn Sie dann eine jrxml-Datei auf den Server kopieren, könnte es eine Fehlermeldung geben in dem Stil

java.lang.NoSuchMethodError:...

Das Vorgehen ist hier wie folgt:

* Prüfen Sie zunächst, ob Sie die jeweilige Bibliothek wirklich brauchen.
* Wenn ja, dann ermitteln Sie aus dem Namen der fehlenden Klasse den Namen der *.jar-Datei. Meist reicht es, wenn Sie den Klassennamen in einer Suchmaschine eingeben, oder in einer speziellen Java-Suchmaschine wie http://www.jarfinder.com/
* Wenn Sie die jar-Datei identifiziert haben, können Sie diese von iReport-xxx/ireport/modules/ext/ in das webapps/superx/WEB-INF/lib Verzeichns kopieren.
* Danach müssen Sie Tomcat neu starten.

<blockquote>Achtung: gehen Sie beim Kopieren in den WEB-INF/lib Ordner möglichst '''sparsam''' um: manchmal gibt es zwischen einzelnen Bibliotheken unerwünschte und unvorhersehbare Querabhängigkeiten, z.B. nutzt eine iReport-Bibliothek xy.jar eine andere Bibliothek vz.jar, welche bereits im Tomcat Server vorhanden ist – aber mit einer anderen Versionsnummer. In diesem Falle kann es zu seltsamen Phänomenen kommen, die sehr schwer zu diagnostizieren sind, bis hin zu einer Instabilität des Servers. Man muss solche Kopiermaßnahmen auf jeden Fall gründlich testen! 
Unter uns: Wir nennen Probleme, die dadurch entstehen können, die "jar-Hölle"...
</blockquote>
Im folgenden sammeln wir ein paar Beispiele für gefahrlose Kopieraktionen.


==== iReport Grafiken in JasperReports ====

Bitte vermeiden Sie, iReport-spezifische "Themes" zu benutzen (z.B. "aegean"), denn dafür würden weitere Bibliotheken benötigt. Wenn Sie z.B. die folgende Fehlermeldung bekommen, wurde ein Theme benutzt:

[[Datei:JasperReports-Handbuch_grafik_theme_error.png]]

Dann sollten Sie die Einstellung für das Objekt (hier das Theme der Grafik) wieder auf default setzen.


==== Weitere Bibliotheken von iReport ====

Bei der Meldung

java.lang.NoSuchMethodError: org.objectweb.asm.ClassWriter

sollten Sie die Bibliotheken

iReport-xxx/ireport/modules/ext/asm.jar

und zur Sicherheit auch

asm-attrs.jar

in den WEB-INF/lib-Ordner kopieren.


= Troubleshooting =


== Report Problem: Class not set for bucket: <<Variable>> ==

Das Problem tritt in iReport 4.1.1 u.a. bei Kreuztabellen auf. Bei diesem Fehler fehlt in der jrxml-datei im Element <bucketExpression> Z.B.: class="java.lang.String". Diese einfach im Editor ergänzen und es funktioniert. Beispiel:

Aus :

<bucketExpression>

wird:

<bucketExpression class="java.lang.String">


== Die jasper Datei ==

Die jasper Datei ist die kompilierte jrxml. Wenn ein Bericht übertragen werden soll, z.B. von dem Entwickler auf den Server oder von dem Development System auch das Produktivsystem immer nur die jrxml Datei übertragen, da es bei Versionsunterschieden in JasperReport zu Fehlern kommt, wenn die Kompilierte Version zur Verfügung steht. Sobald der Bericht ausgeführt wird, erstellt (kompilliert) JasperReports automatisch die jasper Datei.

Wenn die jasper Datei zur verfügung steht, wird auch nur noch diese von JasperReports verwendet und nicht mehr neu kompiliert. Falls Sie also einen Bericht weiter entwickelt haben oder eine neue Version einspielen, löschen Sie direkt die jasper Datei. Ansonsten werden die Änderungen nicht wirksam.


== Im Excel Export fehlen Felder ==

In Excel werden überlappende Elemente nicht angezeigt. Wenn also 2 Elemente übereinander liegen wird in Excel nur das oberste (welches im Vordergrund liegt) angezeigt. Hier ist besonders drauf zu achten, dass visuell 1px Abstand zwischen den Elementen Platz ist. Wenn von beiden Elementen jeweils eine Linie zu sehen ist, ist es korrekt. Wenn nicht, zählt das schon als Überlappung. Dafür im iReport Designer am besten ganz nah heran zoomen um diesen Abstand zu prüfen.

Hier ein Beispiel. Die beiden oberen Elemente überlappen, die unteren nicht:

[[Datei:JasperReports-Handbuch_ireport_excel.png]]


== Hinweis für HisInOne 7.0 Kompatibilität ==

Jrxml-Dateien, die unter iReport 4.1.3 entwickelt wurden und in HisInOne 7.1 funktionieren, können in 7.0. zur Fehlermeldung führen:

java.lang.NoClassDefFoundError: net/sf/jasperreports/compilers/GroovyEvaluator

In der jasperreports5.1.0 (hisinone 7.0) ist die Klasse GroovyEvaluator nicht enthalten, für 7.1 ist die jasperreports-6.1.0.jar enthalten, die enthält den GroovyEvaluator.

Workaround:

language="groovy"

ändern in

language="java"


== HTML Export keinen whitespace ==

Normal macht JR bei HTML-Exporten für den „Seitenumbruch“ eine Reihe von Leerzeilen. Um dies zu vermeiden, setzen Sie die Property IgnorePagination=true:

<jasperReport xmlns="http://jasperreports.sourceforge.net/jasperreports" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://jasperreports.sourceforge.net/jasperreports http://jasperreports.sourceforge.net/xsd/jasperreport.xsd" name="Kaufm. Quartalsbericht" language="groovy" pageWidth="2925" pageHeight="565" orientation="Landscape" columnWidth="2925" leftMargin="0" rightMargin="0" topMargin="0" bottomMargin="0"

isIgnorePagination="true">


== UUID's ==

In Jaspersoft Studio wird an jedes Element eine lange UUID angehängt, in aktuellen Versionen von SuperX/ Edustore macht das keine Probleme. In älteren Versionen bzw. in iReport 4.* schon. Damit der JasperReport abwärtskompatibel ist, muss diese gelöscht werden. Bei großen Berichten taucht diese aber unter Umständen mehrere hundert Mal auf. Hier kann in JasperSoft Studio in dem "Source"-Reiter des Berichtsdesigners nach folgender Regular Expression gesucht werden und diese mit einem Leerzeichen ersetzt werden:

uuid="[0-9a-z-]{36}"


= Weitere Dokus =

<blockquote>Ahammad, S. (2010). iReport 3.7.Learn how to use iReport to create, format, and export reports. Birmingham: Packt
</blockquote>
<blockquote>Haneke, U. et al. (2010). Open Source Business Intelligence. Möglichkeiten, Chancen und Risiken quelloffener BI-Lösungen. Wien: Hanser
</blockquote>
<blockquote>Toffoli, G. (2007). The definitive guide to iReport. Berkeley, CA: Apress
</blockquote>
<blockquote>Noch mehr Infos (nur Englisch) erhält man unter: 
http://jasperforge.org/plugins/project/project_home.php?projectname=ireport
</blockquote>
<blockquote>und natürlich unsere Website:
</blockquote>
<blockquote>http://www.superx-projekt.de/doku/entwicklung/iReport-Handbuch/main.htm
</blockquote>
<blockquote>
</blockquote>

Datei:JasperReports-Handbuch Eingebettet 007.png

2026-07-06T06:23:20Z

Andrek: Die Seite wurde neu angelegt: „Kategorie:JasperReports-Handbuch“

[[Kategorie:JasperReports-Handbuch]]

Datei:JasperReports-Handbuch Eingebettet 008.png

2026-07-06T06:23:19Z

Andrek: Die Seite wurde neu angelegt: „Kategorie:JasperReports-Handbuch“

[[Kategorie:JasperReports-Handbuch]]

Datei:JasperReports-Handbuch Eingebettet 005.png

2026-07-06T06:23:19Z

Andrek: (Benutzername entfernt) (Logbucheinzelheiten entfernt)

[[Kategorie:JasperReports-Handbuch]]

Datei:JasperReports-Handbuch Eingebettet 005.png

2026-07-06T06:23:19Z

Andrek: Die Seite wurde neu angelegt: „Kategorie:JasperReports-Handbuch“

[[Kategorie:JasperReports-Handbuch]]

Datei:JasperReports-Handbuch Eingebettet 002.png

2026-07-06T06:23:19Z

Andrek: (Benutzername entfernt) (Logbucheinzelheiten entfernt)

[[Kategorie:JasperReports-Handbuch]]

Datei:JasperReports-Handbuch Eingebettet 002.png

2026-07-06T06:23:18Z

Andrek: Die Seite wurde neu angelegt: „Kategorie:JasperReports-Handbuch“

[[Kategorie:JasperReports-Handbuch]]

Datei:JasperReports-Handbuch Eingebettet 010.png

2026-07-06T06:23:18Z

Andrek: (Benutzername entfernt) (Logbucheinzelheiten entfernt)

[[Kategorie:JasperReports-Handbuch]]

Datei:JasperReports-Handbuch Eingebettet 010.png

2026-07-06T06:23:18Z

Andrek: Die Seite wurde neu angelegt: „Kategorie:JasperReports-Handbuch“

[[Kategorie:JasperReports-Handbuch]]

Datei:JasperReports-Handbuch Eingebettet 009.png

2026-07-06T06:23:18Z

Andrek: Die Seite wurde neu angelegt: „Kategorie:JasperReports-Handbuch“

[[Kategorie:JasperReports-Handbuch]]

Datei:JasperReports-Handbuch Eingebettet 014.png

2026-07-06T06:23:18Z

Andrek: Die Seite wurde neu angelegt: „Kategorie:JasperReports-Handbuch“

[[Kategorie:JasperReports-Handbuch]]

Datei:JasperReports-Handbuch Eingebettet 013.png

2026-07-06T06:23:17Z

Andrek: Die Seite wurde neu angelegt: „Kategorie:JasperReports-Handbuch“

[[Kategorie:JasperReports-Handbuch]]

Datei:JasperReports-Handbuch Eingebettet 012.png

2026-07-06T06:23:17Z

Andrek:

JasperReports-Handbuch[[Kategorie:JasperReports-Handbuch]]

Datei:JasperReports-Handbuch Eingebettet 012.png

2026-07-06T06:23:17Z

Andrek: JasperReports-Handbuch

JasperReports-Handbuch

Datei:JasperReports-Handbuch Eingebettet 011.png

2026-07-06T06:23:17Z

Andrek: (Benutzername entfernt) (Logbucheinzelheiten entfernt)

[[Kategorie:JasperReports-Handbuch]]

Datei:JasperReports-Handbuch Eingebettet 006.png

2026-07-06T06:23:17Z

Andrek: (Benutzername entfernt) (Logbucheinzelheiten entfernt)

[[Kategorie:JasperReports-Handbuch]]

Datei:JasperReports-Handbuch Eingebettet 011.png

2026-07-06T06:23:17Z

Andrek: Die Seite wurde neu angelegt: „Kategorie:JasperReports-Handbuch“

[[Kategorie:JasperReports-Handbuch]]

Datei:JasperReports-Handbuch Eingebettet 006.png

2026-07-06T06:23:16Z

Andrek: Die Seite wurde neu angelegt: „Kategorie:JasperReports-Handbuch“

[[Kategorie:JasperReports-Handbuch]]

Datei:JasperReports-Handbuch Eingebettet 004.png

2026-07-06T06:23:16Z

Andrek: Die Seite wurde neu angelegt: „Kategorie:JasperReports-Handbuch“

[[Kategorie:JasperReports-Handbuch]]

Datei:JasperReports-Handbuch Eingebettet 003.png

2026-07-06T06:23:16Z

Andrek: Die Seite wurde neu angelegt: „Kategorie:JasperReports-Handbuch“

[[Kategorie:JasperReports-Handbuch]]

Datei:JasperReports-Handbuch Eingebettet 001.png

2026-07-06T06:23:16Z

Andrek: Die Seite wurde neu angelegt: „Kategorie:JasperReports-Handbuch“

[[Kategorie:JasperReports-Handbuch]]

Datei:JasperReports-Handbuch booklet cover1.png

2026-07-06T06:22:33Z

Andrek: JasperReports-Handbuch

JasperReports-Handbuch

Datei:JasperReports-Handbuch styleref design folie.png

2026-07-06T06:22:32Z

Andrek: JasperReports-Handbuch

JasperReports-Handbuch

Datei:JasperReports-Handbuch jaspersoft designer.png

2026-07-06T06:22:32Z

Andrek: JasperReports-Handbuch

JasperReports-Handbuch

Datei:JasperReports-Handbuch booklet preview1.png

2026-07-06T06:22:32Z

Andrek: JasperReports-Handbuch

JasperReports-Handbuch

Datei:JasperReports-Handbuch jaspersoft design properties.png

2026-07-06T06:22:32Z

Andrek: JasperReports-Handbuch

JasperReports-Handbuch

Datei:JasperReports-Handbuch designer ueberblick.png

2026-07-06T06:22:31Z

Andrek: JasperReports-Handbuch

JasperReports-Handbuch

Datei:JasperReports-Handbuch notenschnitt design1.png

2026-07-06T06:22:31Z

Andrek: JasperReports-Handbuch

JasperReports-Handbuch

Datei:JasperReports-Handbuch makro jrxml.png

2026-07-06T06:22:31Z

Andrek: JasperReports-Handbuch

JasperReports-Handbuch

Datei:JasperReports-Handbuch style def folie.png

2026-07-06T06:22:30Z

Andrek: JasperReports-Handbuch

JasperReports-Handbuch

Datei:JasperReports-Handbuch kreuztabelle manuell 2.jpg

2026-07-06T06:22:30Z

Andrek: JasperReports-Handbuch

JasperReports-Handbuch

Datei:JasperReports-Handbuch kreuztabelle manuell 1.jpg

2026-07-06T06:22:30Z

Andrek: JasperReports-Handbuch

JasperReports-Handbuch

Datei:JasperReports-Handbuch jss-ir properties2.png

2026-07-06T06:22:29Z

Andrek: JasperReports-Handbuch

JasperReports-Handbuch

Datei:JasperReports-Handbuch jss-ir properties1.png

2026-07-06T06:22:29Z

Andrek: JasperReports-Handbuch

JasperReports-Handbuch

Datei:JasperReports-Handbuch jss-ir preview2.png

2026-07-06T06:22:29Z

Andrek: JasperReports-Handbuch

JasperReports-Handbuch

Datei:JasperReports-Handbuch jss-ir palette2.png

2026-07-06T06:22:29Z

Andrek: JasperReports-Handbuch

JasperReports-Handbuch

Datei:JasperReports-Handbuch jaspersoft design chart wizard4.png

2026-07-06T06:22:28Z

Andrek: JasperReports-Handbuch

JasperReports-Handbuch