PDF-Briefpapier-Vorlagen

Verwaltung der PDF-Vorlagen, die calServer als Briefpapier unter einen Bericht legt — Administration > Berichtsverwaltung > PDF-Vorlagen.

Diese Seite beschrieb bis 2026-08 etwas anderes

Sie fuehrte „integrierte Reporte" auf (Kalibrierschein Standard, Geraeteuebersicht, Jahresuebersicht …), ein Variablen-Mapping und einen Endpunkt POST /api/v2/reports/generate. Nichts davon existiert. calServer bringt keine Berichtsvorlagen mit, und zwar mit Absicht — siehe Woher Berichtsvorlagen kommen. Was der Menuepunkt wirklich verwaltet, steht hier.

---

Was eine PDF-Vorlage ist

Eine hochgeladene PDF mit dem Firmenlayout — Briefkopf, Fusszeile, Rahmen —, die der ReportOverlayService beim Erzeugen unter die Berichtsseiten legt. Der Bericht selbst bleibt die JasperReports-Vorlage; die PDF liefert nur das Papier.

Gespeichert wird sie in master_report_template, die Datei liegt versioniert im DMS. Je Vorlage werden gefuehrt:

Feld	Bedeutung
template_name	Anzeigename in der Auswahl
total_page	Seitenzahl der hochgeladenen PDF
first_page	welche Seite der PDF unter die erste Berichtsseite kommt
other_page	welche Seite unter alle weiteren kommt
sort_order	Reihenfolge in der Auswahl

Die Trennung first_page / other_page ist der ganze Zweck der Konstruktion: Briefpapier hat typischerweise einen vollen Briefkopf auf Seite 1 und eine schlankere Folgeseite.

Zuordnung an einen Bericht

Im Bericht unter Briefpapier:

Einstellung	use_template	Wirkung
Kein Briefkopf	null	der Bericht rendert ohne Unterlage
Globaler Briefkopf	html	die zentral gepflegten Angaben (Anschrift, Telefon, Akkreditierungsnummer) werden auf jede Seite gerendert
PDF-Vorlage	pdf	die hier verwaltete PDF wird untergelegt (template_uID)

Empfehlung: der globale Briefkopf. Er wird an einer Stelle gepflegt und gilt fuer alle Berichte; eine PDF-Vorlage muss bei jeder Aenderung an Anschrift oder Akkreditierungsnummer neu erzeugt und erneut hochgeladen werden. Die Begruendung steht in ADR-037.

PDF-Vorlagen bleiben richtig, wenn das Papier mehr traegt als Text — Wasser­zeichen, Perforationsmarken, ein gestaltetes Layout, das sich nicht aus Kopf- und Fusszeile herleiten laesst.

Vorlage austauschen

Neues Briefpapier ersetzt die Datei der bestehenden Vorlage — Zeilenmenue Datei austauschen, POST /admin/report-templates/{id}/file. Die Vorlage behaelt ihre uID, jede template_uID in den Berichtseinstellungen bleibt gueltig, die neue PDF wird zur naechsten DMS-Version.

Ein Upload ueber PDF-Vorlage hochladen (POST /admin/report-templates) legt dagegen eine zweite Vorlage an — und die alte laesst sich nicht loeschen, solange ein Bericht sie noch als Briefpapier fuehrt (409 mit den betroffenen Berichten). Fuer den Austausch ist das der falsche Weg.

Traegt die neue PDF weniger Seiten als die alte, werden first_page und other_page auf die letzte vorhandene Seite geklemmt statt auf eine Seite zu zeigen, die es nicht gibt.

Versionierung

Jeder Upload legt eine neue Version im DMS an, die alte bleibt abrufbar:

• GET /admin/report-templates/{id}/versions — Versionsliste
• POST /admin/report-templates/{id}/versions/{versionId}/activate — aeltere Version wieder aktiv schalten
• GET /admin/report-templates/{id}/versions/{versionId}/download — Version herunterladen

Das ist derselbe Mechanismus wie bei den Berichtspaketen selbst. Eine versehentlich hochgeladene Vorlage ist damit ein Klick zurueck, kein Wiederherstellungsfall.

Woher Berichtsvorlagen kommen

Die eigentlichen JasperReports-Vorlagen (.jrxml) sind nicht Teil der Anwendung. Sie werden in calhelp/calServer-reports gepflegt, versioniert und reviewt und stehen unter calhelp.github.io/calServer-reports/downloads als Pakete bereit — siehe Report-Pakete herunterladen.

Das ist eine bewusste Entscheidung und keine Luecke: eine im Anwendungs-Image mitgelieferte Vorlage waere ein Fork der dort gepflegten Fassung. Deshalb legt calServer fuer die drei Systemberichte zwar eine Zeile an, laesst sie aber leer und nennt in der Berichtsverwaltung das Paket, das hineingehoert (LOCATION-JSON-SAMPLE, PRICE-LIST-JSON-SAMPLE, ORDER-JSON-SAMPLE).

Fuer neue Vorlagen gilt die JSON-Datenquelle statt eingebettetem SQL: V2-Berichte mit JSON-Datenquelle.

Bericht erzeugen

Berichte werden an ihrer Entitaet erzeugt, nicht ueber einen zentralen Generierungs-Endpunkt:

GET  /api/v2/calibrations/{ctag}/reports            # verfuegbare Berichte
POST /api/v2/calibrations/{ctag}/reports/generate   # erzeugen
GET  /api/v2/inventories/{mtag}/reports
POST /api/v2/inventories/{mtag}/reports/generate
GET  /api/v2/bookings/{bookingId}/reports
POST /api/v2/bookings/{bookingId}/reports/generate

Gerendert wird im report-runner-Container. Sein Zustand:

docker ps --filter name=report-runner --format '{{.Names}}\t{{.Status}}'
docker logs report-runner --tail 50

Laeuft er nicht, scheitert jeder Bericht mit „Report runner unavailable".