Overview

Reporting

Operational reporting on route #/<route>/report-viewer.

Report Viewer

The report-viewer executes and displays Stimulsoft reports associated with the current metadata route.

Main features:

  • report opening from list/grid with report name (reportName) and optional parameters.
  • runtime data rendering with viewer toolbar (zoom, export, print).
  • filter/parameter support propagated from the calling page.

Designer Reference

For report .mrt creation or modification, see the subsection Report designer in Designer & Workflow.

Report parameters (filtered SQL variables)

To filter a report on a specific entity (e.g. printing a single invoice), the canonical pattern is:

1. In the `.mrt`: declare a Variable in the Dictionary with AllowUseAsSqlParameter = True (Stimulsoft 2026.1+). Use the variable as @paramName in SqlCommands:

Snippet 1SQL
   SELECT ... FROM fatture_inviate WHERE id = @fattura_id
   SELECT ... FROM fatture_inviate_righe WHERE fattura_id = @fattura_id

Pitfall: do NOT use the legacy <StiDataParameter> block in the DataSource — it is no longer supported by the current Stimulsoft version and produces ArgumentException: Int32 is not a valid value for Int32. (Parameter 'value') during report.Load().

2. In the viewer URL: pass the value via the parameters query param (NOT as a direct query param):

Snippet 2text
   ✅ #/<route>/report-viewer?reportName=Report.mrt&parameters=fattura_id%7C%7Ceq%7C%7C42
   ❌ #/<route>/report-viewer?reportName=Report.mrt&fattura_id=42   <-- ignored

parameters URL-encoded syntax: name||eq||value (separated by @ for multiple parameters).

3. From a row action or UI link: use the canonical callback to build the URL:

Snippet 3js
   const recordId = (record && record.id && record.id.value) ?? (record && record.id);
   const params = 'fattura_id||eq||' + recordId;
   window.location.hash = '#/<route>/report-viewer?reportName=Report.mrt&parameters='
                       + encodeURIComponent(params);

Reports in the viewer's language

Report headers are translated with the column label keys (meta-key.<md_route_name>.<mc_nome_colonna>, see Interface translations), in the language of whoever opens the report.

  • Reports created from the "Create report" dialog: every text showing a column label (band headers, group labels, crosstab row and column titles) holds the raw metadata label and carries the key in the Stimulsoft Tag property, which never shows in any rendering (viewer, designer preview, export); a Tag already set by the report author is never overwritten and that text stays without a key. The report title has no key and stays as it is.
  • When the report opens: the viewer sends the user's current language to the server (language parameter, including the override chosen from the user menu). The server replaces the text of every keyed component with the translation for that language read from _wuic_translations (one read per report); without a translation the text written in the .mrt stays.
  • Globalized strings of the designer: if the .mrt has translations written by hand in the Stimulsoft designer for that culture, they are applied after the keys and win.
  • The `.mrt` does not change: translations are never saved into the file; the designer always opens and saves the raw label.
  • Existing reports: the metadata editor item Reports → Add translation keys to reports (super-admin only, refused when the design lock is on) adds the key to the texts of all the route's reports whose content matches the raw label (view or edit) of a column. It leaves expressions, free texts, texts with a Tag chosen by the report author and labels shared by two columns alone; it is idempotent and the result shows reports checked, texts marked and already marked.

Example: with meta-key.ordini.cliente = Kunde in de-DE, the "Cliente" header of the ordini report opens as "Kunde" for a German user and stays "Cliente" for an Italian user.

Report query timeout

AppSettings.reportQueryTimeout (seconds) applies to the report's SQL data sources left at the Designer default timeout (30); the others keep the value saved in the .mrt. If the key is missing or is not a positive integer the backend uses 120 (up to 1.7.13 the key was mandatory: without it, every report with the default timeout answered 400). The packages already include it. Example:

Snippet 4JSON
"AppSettings": {
  "reportQueryTimeout": "120"
}

The viewer's jsonPath parameter (data source read from a JSON file on the server) is reserved to administrators since 1.7.13: for other users the request is refused. Reports with an SQL source and the parameters parameter do not change.

Screenshot

Runtime example with parameters/filter applied to the report
Runtime example with parameters/filter applied to the report
Report viewer opening with report rendering and operational toolbar
Report viewer opening with report rendering and operational toolbar