Managing reports in JasperWho?
A report in JasperWho? is more than a file. It is a fully managed configuration — with its own parameters, data fields, image resources, SQL query, data connection, preview images, rendering history, and print records. This page walks through the complete lifecycle of a report configuration, from upload to print.
[SCREENSHOT: JasperWho? report list — the main ReportConfig overview showing several report cards with thumbnails, context badges, and status indicators.]
The ReportConfig — Central Master Data
The ReportConfig is the core entity in JasperWho?. Every report you manage is a ReportConfig record, and everything else in the system either belongs to it or references it. A single ReportConfig brings together:
.jrxml template file stored on disk
Its parameters — input values passed at render time
Its fields — data columns that populate the detail band
Its resources — graphic assets (images, logos) embedded in the template
Its SQL query — defined and managed directly in JasperWho?
Its data connection — the live database to query (optional)
Its context — an organisational label for grouping
Its preview and thumbnail images — generated from example data
Nothing renders without a ReportConfig. Nothing prints without one either. It is the starting point for every operation in JasperWho?.
The Report Configuration Lifecycle
Upload .jrxml
│
▼
Auto-analysis
(parameters, fields, resources detected and created)
│
▼
Complete the configuration
(upload resource files, set example values, write SQL query, assign connection)
│
▼
Generate preview
(renders with example data, stores preview + thumbnail)
│
▼
Ready to render
Each step is described in detail below.
Uploading a Report
When you upload a .jrxml file, JasperWho? immediately analyses it and builds the initial configuration automatically. The following is extracted from the file:
name attribute on <jasperReport>. Must be unique.
Page dimensions — width and height, converted from Jasper pixels to millimetres.
Detail band presence — whether the report has a repeating data section.
Parameters — all non-resource parameters, including their data types and any exampleValue / required custom properties set in the .jrxml.
Fields — all data fields, including their data types and exampleValue custom properties.
Resources — all parameters following the P_RESOURCE_ naming convention (image assets).
The result is a fully structured ReportConfig record with all its child records in place — but not yet complete. Resource files still need to be uploaded, and the SQL query still needs to be written if a live data connection is used.
ReportConfig with the same report name or the same file name already exists.
[SCREENSHOT: JasperWho? — the Create ReportConfig form, showing the file upload field, Context selector, and optional Connection Config dropdown.]
Completing the Configuration
After upload, the report configuration is ready but not yet fully operational. The following steps complete it:
Upload Resource Files
If the report contains image resources (detected as P_RESOURCE_ parameters), each one requires an actual file to be uploaded. JasperWho? cannot render the report until all resource files are in place.
Alternatively, a resource can be linked to a CommonReportResource — a shared asset reused across multiple reports, such as a company logo. Linking is permanent: the resource's own file is deleted and the common file is used in its place.
[SCREENSHOT: JasperWho? — the Resources section of a ReportConfig edit page, showing one resource with a file uploaded and another still missing its file (shown with a warning indicator).]
Review Parameters and Fields
JasperWho? picks up exampleValue and required custom properties from the .jrxml automatically on upload. If these were not set in Jaspersoft Studio, or if you need to adjust them, you can do so directly in the configuration.
Every parameter and field should have an example value set before generating a preview.
Write the SQL Query and Assign a Connection
If the report fetches live data from a database, assign a ReportConnectionConfig and write the SQL query in the Query field. The query is stored in JasperWho? — not in the .jrxml.
Parameters are available as named bindings in the query (:PARAMETER_NAME). See Creating reports in Jaspersoft Studio for details on how parameter binding works.
A connection is not required if the report has no detail band, or if data will be delivered in the render request itself.
Generating a Preview
Once all resource files are uploaded and all parameters and fields have example values, you can generate a preview. JasperWho? renders the report using the stored example values — no live data needed — and stores the result as a base64-encoded PDF and a thumbnail image on the ReportConfig.
The preview is used in the report list as a visual card and as a quick sanity check that the template renders correctly. It is also what the useExampleValues flag triggers during a render request — useful for testing without providing real data.
[SCREENSHOT: JasperWho? — a ReportConfig detail page showing the generated preview thumbnail and a "Generate Preview" button. Ideally show both a config with a thumbnail and one without.]
Report History Records
Every render request can optionally create a ReportHistoryRecord — a full log entry of what was requested and what was returned. This is controlled by the createHistoryRecord flag in the render request body and is off by default.
When enabled, the history record captures:
ok, render_fail, error, unknown)
The trace ID for cross-referencing with logs
History records are valuable for traceability — you can see exactly what was rendered, when, with what data, and what the result was. From a history record, you can also dispatch a reprint directly.
When to Skip History Records
History records are entirely optional. There are two good reasons to leave them off:
Performance and storage. Storing the full PDF, request payload, and response for every render adds up. For high-frequency rendering where traceability is not needed, skipping history records keeps the database lean.
Data sensitivity. A history record stores the complete render payload — including all parameters and data passed to the report. If that data is sensitive (personal data, financial figures, medical information), you may not want it persisted on the server at all. Omitting createHistoryRecord from the render request ensures nothing is logged.
Retention
History records are automatically purged after a configurable number of days. The retention period is set via the PURGE_HISTORY_DAYS environment variable (default: 30 days). Purging runs automatically as a background job — no manual intervention required.
[SCREENSHOT: JasperWho? — the History Records list for a specific ReportConfig, showing entries with status badges, timestamps, and a thumbnail column.]
Report Print Tasks
A ReportPrintTask sends a rendered PDF to a physical printer. Print tasks are created as part of a render request — you render and dispatch to a printer in a single call — by setting createPrintTask: true and providing a printerName.
Print tasks are always linked to a ReportHistoryRecord. This means creating a print task also creates a history record (regardless of whether createHistoryRecord is explicitly set), so the printed document is always traceable.
How Printing Works
JasperWho? does not communicate with printers directly. Instead, it creates a ReportPrintTask record and notifies a separate print service — a lightweight C# application running on or near the target machine — which picks up the task and executes the print job.
There are two modes of delivery:
WebSocket (push). If a broadcastId is included in the render request, JasperWho? broadcasts a ReportPrintTaskCreated event via WebSocket (Laravel Reverb) the moment the task is created. The print service subscribes to that channel and reacts immediately. This is the recommended mode for real-time printing — the task reaches the printer within milliseconds of the render completing.
Polling (pull). Without a broadcastId, no broadcast is sent. The print service must poll the API for new tasks in pending status. This works fine for less time-sensitive workflows.
Print Task Status
The print service reports status back to JasperWho? via the API after executing the job. The error_message field on the task record contains the failure detail if printing did not succeed.
Copies
The numberOfCopies field controls how many copies the print service should produce. It defaults to 1 if not specified.
PURGE_PRINTTASKS_DAYS days (default: 30). Like history record purging, this runs in the background without any manual action.
[SCREENSHOT: JasperWho? — a Print Task list or the detail view of a single print task, showing the status badge, printer name, copies, and linked history record.]
Deleting a Report Configuration
A ReportConfig can only be deleted when no ReportHistoryRecord or ReportPrintTask references it. JasperWho? will reject a deletion request while any such records exist.
When a ReportConfig is deleted, the following is removed along with it: the .jrxml file from disk, all resource files, and all parameter and field records. The deletion is atomic — if any step fails, the entire operation is rolled back.