Skip to main content

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.

        Weiterführende Seiten

          Template-Parameter-Referenz Deployment-Guide API-Authentifizierung
          Back to top