# Managing reports in JasperWho?

<div style="text-align: justify;">

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.

[![main-menu-2.png](https://docs.jasper-who.kiwi-software.dev/uploads/images/gallery/2026-05/scaled-1680-/main-menu-2.png)](https://docs.jasper-who.kiwi-software.dev/uploads/images/gallery/2026-05/main-menu-2.png)

---

<h3 id="the-reportconfig" style="color: #203671; margin-top: 2.2em;">The ReportConfig — Central Master Data</h3>

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:

- The **`.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?.

---

<h3 id="lifecycle" style="color: #203671; margin-top: 2.2em;">The Report Configuration Lifecycle</h3>

```
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.

---

<h3 id="uploading" style="color: #203671; margin-top: 2.2em;">Uploading a Report</h3>

When you upload a `.jrxml` file, JasperWho? immediately analyses it and builds the initial configuration automatically. The following is extracted from the file:

- **Report name** — from the `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.

<div style="border-left: 4px solid #203671; background: #f0f3fb; padding: 10px 16px; margin: 16px 0; border-radius: 0 4px 4px 0;">
⚠️ <strong>Report name and file name must be unique.</strong> JasperWho? will reject an upload if a <code>ReportConfig</code> with the same report name or the same file name already exists.
</div>

[![report-config-create.png](https://docs.jasper-who.kiwi-software.dev/uploads/images/gallery/2026-05/scaled-1680-/report-config-create.png)](https://docs.jasper-who.kiwi-software.dev/uploads/images/gallery/2026-05/report-config-create.png)

---

<h3 id="completing" style="color: #203671; margin-top: 2.2em;">Completing the Configuration</h3>

After upload, the report configuration is ready but not yet fully operational. The following steps complete it:

<h4 style="color: #203671; margin-top: 1.4em;">Upload Resource Files</h4>

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.

[![report-resource-edit.png](https://docs.jasper-who.kiwi-software.dev/uploads/images/gallery/2026-05/scaled-1680-/report-resource-edit.png)](https://docs.jasper-who.kiwi-software.dev/uploads/images/gallery/2026-05/report-resource-edit.png)

<h4 style="color: #203671; margin-top: 1.4em;">Review Parameters and Fields</h4>

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.

<h4 style="color: #203671; margin-top: 1.4em;">Write the SQL Query and Assign a Connection</h4>

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.

---

<h3 id="preview" style="color: #203671; margin-top: 2.2em;">Generating a Preview</h3>

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.

<div style="border-left: 4px solid #5fc75d; background: #f6fdf6; padding: 10px 16px; margin: 16px 0; border-radius: 0 4px 4px 0;">
ℹ️ <strong>Preview generation will fail if any resource file is missing or any example value is not set.</strong> JasperWho? checks all three conditions — resources, parameter example values, and field example values — before attempting to render.
</div>

[![report-config-preview.png](https://docs.jasper-who.kiwi-software.dev/uploads/images/gallery/2026-05/scaled-1680-/report-config-preview.png)](https://docs.jasper-who.kiwi-software.dev/uploads/images/gallery/2026-05/report-config-preview.png)

---

<h3 id="history-records" style="color: #203671; margin-top: 2.2em;">Report History Records</h3>

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:

- The exact request payload sent to the render endpoint
- The full API response
- The rendered PDF (Base64-encoded)
- A thumbnail of the first page (generated asynchronously in the background)
- The rendering status (`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.

<h4 style="color: #203671; margin-top: 1.4em;">When to Skip History Records</h4>

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.

<h4 style="color: #203671; margin-top: 1.4em;">Retention</h4>

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.

[![report-history-record-index.png](https://docs.jasper-who.kiwi-software.dev/uploads/images/gallery/2026-05/scaled-1680-/report-history-record-index.png)](https://docs.jasper-who.kiwi-software.dev/uploads/images/gallery/2026-05/report-history-record-index.png)

---

<h3 id="print-tasks" style="color: #203671; margin-top: 2.2em;">Report Print Tasks</h3>

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.

<h4 style="color: #203671; margin-top: 1.4em;">How Printing Works</h4>

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.

<h4 style="color: #203671; margin-top: 1.4em;">Print Task Status</h4>

| Status | Meaning |
|---|---|
| <span style="color: #203671; font-weight: 600;">pending</span> | Created, waiting for the print service to pick it up |
| <span style="color: #349b31; font-weight: 600;">printed</span> | Print job executed and confirmed by the print service |
| <span style="color: #c0392b;">error</span> | Print service reported a failure |
| <span style="color: #525E5A;">unknown</span> | Status could not be determined |

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.

<h4 style="color: #203671; margin-top: 1.4em;">Copies</h4>

The `numberOfCopies` field is passed to the print service as the requested number of printed copies. It defaults to `1` if not specified. JasperWho? always renders the PDF exactly once — the print service is responsible for duplicating the output on the printer side.

<div style="border-left: 4px solid #5fc75d; background: #f6fdf6; padding: 10px 16px; margin: 16px 0; border-radius: 0 4px 4px 0;">
ℹ️ <strong>Print tasks also have configurable retention.</strong> They are automatically purged after <code>PURGE_PRINTTASKS_DAYS</code> days (default: 30). Like history record purging, this runs in the background without any manual action.
</div>

[![report-print-task-index.png](https://docs.jasper-who.kiwi-software.dev/uploads/images/gallery/2026-05/scaled-1680-/report-print-task-index.png)](https://docs.jasper-who.kiwi-software.dev/uploads/images/gallery/2026-05/report-print-task-index.png)

---

<h3 id="deletion" style="color: #203671; margin-top: 2.2em;">Deleting a Report Configuration</h3>

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.

<div style="border-left: 4px solid #203671; background: #f0f3fb; padding: 10px 16px; margin: 16px 0; border-radius: 0 4px 4px 0;">
⚠️ <strong>To delete a ReportConfig that has history records or print tasks, those records must be removed first.</strong> Once the retention period has passed and the automatic purge has run, or once the records are manually deleted, the ReportConfig can be removed.
</div>

</div>