Parameter im Report-Paket beschreiben¶

Gilt nur fuer JSON-Berichte

Der Parameter-Katalog steht ausschliesslich fuer V2-JSON-Berichte zur Verfuegung -- Bundles ohne eingebettetes SQL, die aus einem JSON-Datensatz gefuellt werden (siehe V2-Berichte mit JSON-Datenquelle und ADR-009). Klassische V1/JDBC-Bundles bekommen keinen Katalog; fuer sie sieht die Berichtsvariablen-Verwaltung unveraendert aus.

JasperReports-Vorlagen tragen ihre Anpassungsparameter bereits in sich: jede Vorlage deklariert <parameter>-Elemente ($P{...}), ueber die Fusszeilen, Logos, Labor-Identitaet oder Textbausteine gesteuert werden. Konfiguriert werden diese Parameter in calServer ueber Berichtsvariablen (Administration > Berichtsverwaltung > Berichtsvariablen).

Damit dieser Weg nicht laenger Handarbeit ist, kann das Report-Paket einen Parameter-Katalog mitliefern. calServer liest ihn direkt aus dem hochgeladenen ZIP und bietet die Parameter mit Beschreibung, Typ und Standardwert zur Auswahl an -- statt eines leeren Freitextfelds.

Woher der Katalog kommt¶

Es gibt zwei Quellen mit klarer Vorrangregel (kein Merge):

Manifest parameters.json an der Bundle-Wurzel (empfohlen): volle Metadaten inkl. Beschreibung, Eingabetyp, Auswahloptionen, Gruppierung und Mehrsprachigkeit. Liegt ein Manifest bei, gilt nur das Manifest.
JRXML-Fallback (Bestandspakete ohne Manifest): calServer leitet den Katalog aus den <parameter>-Deklarationen des Haupt-JRXML ab (<parameterDescription>, defaultValueExpression, optionale calserver.*-Properties).

Ohne auswertbare Deklarationen verhaelt sich alles wie bisher (kein Katalog).

Das Manifest `parameters.json`¶

Die Datei liegt neben main_reports/ (gleiche Ebene wie die README). Format und Schema werden im Repository calhelp/calServer-reports gepflegt (schema/report-parameters.schema.json). Beispiel:

{
  "$schema": "https://calhelp.github.io/calServer-reports/schema/report-parameters.schema.json",
  "version": 1,
  "parameters": [
    {
      "name": "Company_footer",
      "label": { "de": "Fusszeile", "en": "Footer" },
      "description": {
        "de": "Text am unteren Rand jeder Seite, z. B. Firmenname und Akkreditierungshinweis.",
        "en": "Text at the bottom of every page, e.g. company name and accreditation notice."
      },
      "role": "variable",
      "scope": "type",
      "input": "textarea",
      "default": "",
      "group": "Layout"
    }
  ]
}

Felder¶

Feld	Pflicht	Bedeutung
`name`	ja	Exakter JRXML-Parametername (`$P{...}`). Muss im Haupt-JRXML deklariert sein -- ausser bei `role: data`, das keinen Layout-Parameter beschreibt.
`label`	ja	Anzeigename; String oder Sprachobjekt (`de`, `en`, ...). Vorbefuellt das Variablen-Label.
`description`	empfohlen	Erklaertext; wird im Dialog als Hilfetext angezeigt, nicht gespeichert.
`role`	nein	`variable` (Admin-Konfiguration, als JRXML-Parameter injiziert) - `data` (Berichtsvariable, die den Datensatz steuert statt das Layout) - `prompt` (Nutzerabfrage beim Generieren) - `system` (nie anbieten). Default `variable`.
`scope`	nein	Empfohlener Geltungsbereich: `report`, `type`, `global`. Nur Vorauswahl -- der Admin bleibt frei.
`input`	nein	Eingabe-Widget: `text`, `textarea`, `select`, `boolean`, `number`, `date`, `color`, `image`. Default `text`.
`options`	bei `select`	Erlaubte Werte: `["A4", "Letter"]` oder `[{"value": "A4", "label": {"de": "DIN A4"}}]`.
`default`	nein	Standardwert als String (befuellt den Inhalt vor).
`required`	nein	Kennzeichnung im Dialog.
`group` / `order`	nein	Gruppierung und Reihenfolge in der Auswahlliste.
`example`	nein	Beispielwert als Platzhaltertext.

Namenskonvention (die `ucfirst`-Stolperfalle)¶

calServer injiziert Berichtsvariablen als $P{ucfirst(variable_name)}. Damit ein Parameter ueber eine Berichtsvariable erreichbar ist, muss sein JRXML-Name mit einem Grossbuchstaben beginnen (Company_footer, nicht company_footer).

Der vorgeschlagene Variablenname ist lcfirst(name) -- Parameter Company_footer wird zur Variable company_footer.
Parameter mit role: variable, deren Name kleingeschrieben beginnt, erzeugen beim Upload und im CI-Check eine Warnung (von der Variablenaufloesung nicht erreichbar).

`role: data` -- Variablen, die den Datensatz steuern¶

Nicht jede Berichtsvariable geht ins Layout. Einige entscheiden, was calServer ueberhaupt in den JSON-Datensatz schreibt, bevor der Bericht ihn sieht. Sie sind keine JRXML-Parameter, werden unter ihrem Rohnamen gelesen (duerfen also kleingeschrieben sein) und stehen deshalb mit role: data im Manifest -- der Upload-Check verlangt fuer sie keine Deklaration im Layout und warnt nicht wegen Kleinschreibung. Angeboten und angelegt werden sie wie jede andere Variable.

Das wichtigste Beispiel ist procedure_field im DAkkS-Kalibrierschein: Es benennt das Kalibrierfeld, in dem der Name der Pruefprozedur steht (V1-Original C2320). Erst damit fuellt calServer den procedure-Block, und erst dann drucken Kalibriergegenstand, Kalibrierverfahren, Verfahrensanweisung und Messbedingungen das, was an der Pruefprozedur gepflegt ist. Ohne die Variable bleibt der Block leer und der Schein faellt auf seine Textbausteine zurueck -- derselbe Text fuer jedes Geraet, ohne dass irgendwo ein Fehler erscheint.

Reservierte Namen (data_contract, Reportpath, PrefixTable, die REPORT_*-Standardparameter sowie Entity-Parameter des Grids wie CTAG, InventoryId, Auftragsnummer) werden immer als system behandelt -- egal, was das Manifest behauptet.

So arbeitest du im calServer¶

Berichtsvariable aus dem Paket anlegen¶

Administration > Berichtsverwaltung > Berichtsvariablen > Berichtsvariable erstellen oeffnen.
Den Bericht waehlen. Ist es ein V2-JSON-Bericht mit Katalog, erscheint ueber dem Variablennamen das Select "Parameter aus dem Report-Paket".
Einen Parameter auswaehlen: Name, Label und Inhalt werden vorbefuellt, die Beschreibung erscheint als Hilfetext, und das Eingabefeld richtet sich nach dem input-Typ (Textarea, Auswahl, Schalter, Datum, ...). Bereits konfigurierte Parameter sind mit einem Haken markiert.
Freitext bleibt jederzeit moeglich -- das Select ist ein Angebot, kein Zwang. Bei Bundles ohne Katalog erscheint es gar nicht.

Paket-Inspektion¶

Der Dialog "Report-Paket" (Schaltflaeche an der Vorlage) zeigt fuer V2-JSON-Bundles zusaetzlich einen Abschnitt "Parameter": Name, Label, Typ, Default, Beschreibung, den Status (konfiguriert/fehlt) sowie die Upload-Warnungen. So siehst du unmittelbar nach dem Hochladen, was das Paket erwartet.

Robustheit¶

Ein fehlerhaftes oder fehlendes Manifest blockiert niemals Upload oder Berichtsgenerierung -- schlimmstenfalls verhaelt sich das System wie ohne Katalog. Beschreibungen werden nie in der Datenbank gespeichert, sondern stets live aus dem Paket gelesen; die V1-geteilte Tabelle master_report_variable bleibt unveraendert.

Fuer Berichtsentwickler¶

Das Pflegen des Manifests, das Generator-Skript und der CI-Validator sind im Report-Repository dokumentiert: calhelp/calServer-reports (scripts/generate_parameters_manifest.py, scripts/check_parameters_manifest.py). Referenz-Bundle: DAKKS-JSON-SAMPLE.