Describing parameters in the report package

JSON reports only

The parameter catalog is available only for V2 JSON reports -- bundles without embedded SQL that are filled from a JSON dataset (see Authoring V2 reports with a JSON data source and ADR-009). Classic V1/JDBC bundles get no catalog; for them the report-variable management looks exactly as before.

JasperReports templates already carry their customization parameters: every template declares <parameter> elements ($P{...}) that drive footers, logos, laboratory identity or text blocks. In calServer these parameters are configured via report variables (Administration > Report Management > Report Variables).

So this no longer has to be manual work, a report package can ship a parameter catalog. calServer reads it straight from the uploaded ZIP and offers the parameters with description, type and default value -- instead of an empty free-text field.

Where the catalog comes from

There are two sources with a strict precedence rule (no merge):

1. Manifest parameters.json at the bundle root (recommended): full metadata including description, input type, options, grouping and multilingual labels. When a manifest is present, only the manifest applies.
2. JRXML fallback (existing packages without a manifest): calServer derives the catalog from the <parameter> declarations of the main JRXML (<parameterDescription>, defaultValueExpression, optional calserver.* properties).

Without usable declarations everything behaves as before (no catalog).

The parameters.json manifest

The file sits next to main_reports/ (same level as the README). Format and schema are maintained in the calhelp/calServer-reports repository (schema/report-parameters.schema.json). Example:

{
  "$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"
    }
  ]
}

Fields

Field	Required	Meaning
name	yes	Exact JRXML parameter name ($P{...}). Must be declared in the main JRXML.
label	yes	Display name; string or per-language object (de, en, ...). Pre-fills the variable label.
description	recommended	Help text; shown in the dialog, not stored.
role	no	variable (admin config) - prompt (user prompt at generation) - system (never offered). Default variable.
scope	no	Suggested scope: report, type, global. Only a pre-selection -- the admin stays free.
input	no	Input widget: text, textarea, select, boolean, number, date, color, image. Default text.
options	for select	Allowed values: ["A4", "Letter"] or [{"value": "A4", "label": {"de": "DIN A4"}}].
default	no	Default value as string (pre-fills the content).
required	no	Marker in the dialog.
group / order	no	Grouping and ordering in the picker.
example	no	Example value as placeholder text.

Naming convention (the ucfirst pitfall)

calServer injects report variables as $P{ucfirst(variable_name)}. For a parameter to be reachable via a report variable, its JRXML name must start with an uppercase letter (Company_footer, not company_footer).

• The suggested variable name is lcfirst(name) -- parameter Company_footer becomes variable company_footer.
• Parameters with role: variable whose name starts lowercase raise a warning on upload and in the CI check (not reachable by variable resolution).

Reserved names (data_contract, Reportpath, PrefixTable, the REPORT_* standard parameters, and the grid's entity parameters such as CTAG, InventoryId, Auftragsnummer) are always treated as system -- no matter what the manifest claims.

Working in calServer

Create a report variable from the package

1. Open Administration > Report Management > Report Variables > Create report variable.
2. Choose the report. If it is a V2 JSON report with a catalog, a select "Parameter from the report package" appears above the variable name.
3. Pick a parameter: name, label and content are pre-filled, the description is shown as help text, and the input field follows the input type (textarea, select, switch, date, ...). Already-configured parameters are marked with a check.
4. Free text is always possible -- the select is an offer, not a lock. For bundles without a catalog it does not appear at all.

Package inspection

The "Report package" dialog (button on the template) shows an extra "Parameters" section for V2 JSON bundles: name, label, type, default, description, status (configured/missing) and the upload warnings. This lets you see immediately after uploading what the package expects.

Robustness

A defective or missing manifest never blocks upload or report generation -- at worst the system behaves as if there were no catalog. Descriptions are never stored in the database but always read live from the package; the V1-shared master_report_variable table stays untouched.

For report developers

Maintaining the manifest, the generator script and the CI validator are documented in the report repository: calhelp/calServer-reports (scripts/generate_parameters_manifest.py, scripts/check_parameters_manifest.py). Reference bundle: DAKKS-JSON-SAMPLE.