What is JasperWho?

JasperWho – Technische Übersicht

JasperWho ist eine Laravel-Anwendung zur Verwaltung und Generierung von JasperReports-Templates. Sie stellt eine API bereit, über die Templates hochgeladen, konfiguriert und als PDF gerendert werden können.

Architektur

Die Anwendung folgt dem Standard-Laravel-MVC-Muster und ist in folgende Schichten aufgeteilt:

API-Layer – RESTful Endpunkte für Template-Management und Rendering
Service-Layer – Geschäftslogik, Jasper-Integration, Dateitransformation
Storage-Layer – Persistenz der Templates, Parameter-Definitionen und generierten Dokumente

Jasper-Integration

JasperWho kommuniziert mit einem JasperReports-Server via HTTP. Die Verbindungsdaten werden pro Umgebung in .env konfiguriert.

JASPER_HOST=https://jasper.example.com
JASPER_USER=admin
JASPER_PASSWORD=secret
JASPER_TIMEOUT=30

Template-Lifecycle

Ein Template durchläuft folgende Zustände:

Upload – .jrxml-Datei wird hochgeladen und validiert
Registrierung – Metadaten und Parameter werden in der Datenbank gespeichert
Deployment – Template wird auf den Jasper-Server übertragen
Rendering – API-Request mit Parametern triggert die PDF-Generierung
Archivierung – Generierte Dokumente werden optional gespeichert

API-Endpunkte

Methode	Endpunkt	Beschreibung
`GET`	`/api/templates`	Alle Templates auflisten
`POST`	`/api/templates`	Neues Template hochladen
`GET`	`/api/templates/{id}`	Template-Details abrufen
`DELETE`	`/api/templates/{id}`	Template löschen
`POST`	`/api/templates/{id}/render`	PDF rendern

Render-Request (Beispiel)

{
  "parameters": {
    "report_date": "2026-05-22",
    "customer_id": 4711,
    "include_charts": true
  },
  "format": "PDF"
}

Konfiguration

Info Alle Umgebungsvariablen können über .env oder als Container-Secrets gesetzt werden.

Variable	Pflicht	Standardwert	Beschreibung
`JASPER_HOST`	✅	–	URL des Jasper-Servers
`JASPER_USER`	✅	–	Benutzername
`JASPER_PASSWORD`	✅	–	Passwort
`JASPER_TIMEOUT`	❌	`30`	Timeout in Sekunden
`TEMPLATE_DISK`	❌	`local`	Laravel-Filesystem-Disk für Templates

Fehlerbehandlung

Schlägt ein Render-Job fehl, gibt die API eine strukturierte Fehlerantwort zurück:

{
  "error": "render_failed",
  "message": "JasperReports server returned 500",
  "template_id": 42,
  "trace_id": "a3f9c1"
}

Häufige Ursachen:

Ungültige Parameter (Typ-Mismatch gegenüber .jrxml-Definition)
Jasper-Server nicht erreichbar (Timeout)
Template nicht deployed (Status ≠ active)

Lokale Entwicklung

# Abhängigkeiten installieren
composer install

# Umgebung vorbereiten
cp .env.example .env
php artisan key:generate

# Datenbank migrieren
php artisan migrate --seed

# Server starten
php artisan serve

Warning Für lokale Entwicklung wird kein echter Jasper-Server benötigt — der JasperFakeDriver simuliert Rendering und gibt Dummy-PDFs zurück.