Configuration and data models
Configuration and Data Models
JasperWho is built around a small set of interconnected models. Understanding them is the key to understanding everything else — from how reports are set up, to how renderings are stored, to how print jobs are dispatched.
This page is the reference you will come back to.
The Model Hierarchy
ReportContext
ReportConnectionConfig
ReportConfig
├── ReportParameter
├── ReportField
└── ReportResource ──(optional link)── CommonReportResource
ReportHistoryRecord
└── ReportPrintTask
Each level builds on the previous. A ReportConfig is the central entity — it connects a .jrxml template with a context, an optional data source, and all its parameters, fields and resources. Every time a report is rendered, a ReportHistoryRecord is created. If that rendering is sent to a printer, a ReportPrintTask is created on top of it.
ReportContext
A context is a label and visual tag you assign to report configurations to group and identify them. It carries no functional logic — it is purely organisational.
| Field | Description |
|---|---|
context_name |
Display name of the context |
context_description |
Short description |
context_text_color |
Hex color for the label text |
context_badge_color |
Hex color for the badge background |
context_border_color |
Hex color for the badge border |
Every ReportConfig requires a context. A context can be shared across any number of report configurations.
ReportConnectionConfig
A connection config represents a database connection that JasperWho can use as a live data source when rendering a report. If a report uses a SQL query defined in its .jrxml, JasperWho executes that query against this connection at render time and passes the result rows to JasperReports as field data.
| Field | Description |
|---|---|
connection_name |
Friendly name for this connection |
connection_driver |
Database driver (see below) |
connection_host |
Hostname or IP |
connection_port |
Port (defaults to driver standard if empty) |
connection_database |
Database / schema name |
connection_username |
Username (stored encrypted) |
connection_password |
Password (stored encrypted) |
connection_test_query |
Optional SQL query used to verify the connection |
connection_tested |
Whether the connection has been successfully tested |
Supported drivers:
| Driver value | Database |
|---|---|
mysql |
MySQL |
mariadb |
MariaDB |
pgsql |
PostgreSQL |
sqlsrv |
Microsoft SQL Server |
Connection status is derived from connection_tested:
| Status | Meaning |
|---|---|
approved |
Connection has been tested successfully |
unapproved |
Never tested, or last test failed |
A ReportConnectionConfig is optional per ReportConfig. Reports that use static example data or no SQL query at all do not require one.
ReportConfig
The ReportConfig is the core entity of JasperWho. It represents a single JasperReports template — the .jrxml file — together with everything JasperWho knows about it.
| Field | Description |
|---|---|
report_name |
Display name of the report |
report_description |
Optional description |
report_file_name |
Internal filename of the stored .jrxml |
report_width |
Width extracted from the .jrxml |
report_height |
Height extracted from the .jrxml |
report_query |
SQL query extracted from the .jrxml (if any) |
report_has_detail_band |
Whether the template contains a detail band |
report_context_id |
FK → ReportContext |
report_connection_config_id |
FK → ReportConnectionConfig (nullable) |
report_preview_base64 |
Base64-encoded preview image |
report_thumbnail_base64 |
Base64-encoded thumbnail image |
When a .jrxml file is uploaded, JasperWho automatically analyses it and creates the associated ReportParameter, ReportField, and ReportResource records. You then review and complete the auto-generated data (e.g. set example values, upload resource files).
ReportParameter
Parameters are the inputs passed into a report at render time — dates, IDs, filter values, flags, and so on.
| Field | Description |
|---|---|
parameter_name |
Parameter name as defined in the .jrxml |
parameter_data_type |
Data type (e.g. String, Integer, Date) |
parameter_required |
Whether this parameter must be supplied |
parameter_evaluation |
Evaluation time from the .jrxml |
parameter_example_value |
Example value used for preview rendering |
ReportField
Fields represent the columns returned by the report's SQL query — the data that populates the detail rows of a report.
| Field | Description |
|---|---|
field_name |
Field name as defined in the .jrxml |
field_data_type |
Data type (e.g. String, BigDecimal, Date) |
field_example_value |
Example value used for preview rendering (when no live DB connection is used) |
ReportResource
Resources are binary file assets embedded in the report template — custom fonts, images, sub-report .jrxml files, and similar.
| Field | Description |
|---|---|
parameter_name |
Resource parameter name as referenced in the .jrxml |
resource_file_name |
Internal filename of the uploaded resource file |
common_report_resource_id |
FK → CommonReportResource (nullable) |
A resource can either be uploaded directly for a specific report, or it can be linked to a CommonReportResource — a shared asset that can be reused across multiple report configurations.
CommonReportResource
A CommonReportResource is a shared file asset that can be linked to multiple report configurations. This is useful for assets that appear in many reports — a company logo, a shared font, a standard header sub-report.
| Field | Description |
|---|---|
resource_name |
Display name |
resource_description |
Optional description |
resource_file_name |
Internal filename of the stored file |
When a ReportResource is linked to a CommonReportResource, it uses the common file instead of its own. Updating the common resource automatically applies to all linked report configurations.
ReportHistoryRecord
Every time a report is rendered through JasperWho — via the frontend or the API — a ReportHistoryRecord is created. This record captures the full context of the rendering: what was requested, what JasperReports responded, and whether it succeeded.
| Field | Description |
|---|---|
report_config_id |
FK → ReportConfig |
trace_id |
Unique identifier for this rendering run |
output_type |
How the PDF was returned (see below) |
report_api_payload |
The exact payload sent to JasperReports |
report_api_response |
The raw response from JasperReports |
report_pdf_base64 |
Base64-encoded PDF (if stored) |
report_pdf_file_name |
Filename on disk (if stored as file) |
report_thumbnail_base64 |
Base64-encoded thumbnail of the first page |
status |
Outcome of the rendering (see below) |
Output types (output_type):
| Value | Description |
|---|---|
base64 |
PDF returned as Base64 string in the response |
url |
PDF stored as a file, URL returned |
preview |
Rendered for preview purposes only |
none |
PDF not returned (e.g. print-only flows) |
Status values (status):
| Value | Description |
|---|---|
ok |
Rendering succeeded, PDF received |
render_fail |
No errors reported but no PDF received |
error |
JasperReports returned one or more errors |
unknown |
Status cannot be determined |
History records are retained for a configurable number of days (see Environment Configuration below). Thumbnails are generated asynchronously after the rendering completes.
ReportPrintTask
A ReportPrintTask is created when a rendered PDF is dispatched to a physical printer. It is always linked to a ReportHistoryRecord — you print a specific past rendering, not a report config directly.
| Field | Description |
|---|---|
report_config_id |
FK → ReportConfig |
report_history_record_id |
FK → ReportHistoryRecord |
trace_id |
Unique identifier for this print run |
broadcast_id |
WebSocket broadcast channel ID |
printer_name |
Target printer name |
copies |
Number of copies to print |
output_file_name |
Filename of the PDF sent to the printer |
output_base64_string |
Base64 PDF (used by the print service) |
error_message |
Error detail if printing failed |
status |
Current print status (see below) |
Status values (status):
| Value | Description |
|---|---|
pending |
Task created, waiting for the print service to pick it up |
printed |
Successfully printed |
error |
Printing failed |
unknown |
Status cannot be determined |
When a print task is created, its ID is broadcast over WebSocket (via Laravel Reverb). The C# print service receives this event, pulls the task data via the API, executes the print job, and updates the status back.
Audit Trail
Every model in JasperWho tracks who created and last updated a record, and with which API token. This information is available on all records via the withAudit query parameter in the API.
| Field | Description |
|---|---|
created_at |
Timestamp of creation |
created_by |
User ID of the creator |
created_by_token_id |
API token ID used for creation (if via API) |
updated_at |
Timestamp of last update |
updated_by |
User ID of the last updater |
updated_by_token_id |
API token ID used for the last update (if via API) |
Environment Configuration
JasperWho exposes several runtime settings via environment variables. These can be set in .env or as container environment variables.
| Variable | Default | Description |
|---|---|---|
APP_SCHEME |
http |
URL scheme used for generated links (http or https) |
API_RATE_LIMIT_PER_MINUTE |
10 |
Maximum API requests per minute per token |
PURGE_HISTORY_DAYS |
30 |
Age (in days) after which history records are purged |
PURGE_PRINTTASKS_DAYS |
30 |
Age (in days) after which print tasks are purged |
PURGE_ORPHANED_FILES_DAYS |
30 |
Age (in days) after which orphaned files on disk are purged |
PAGINATION_DEFAULT_COUNT |
25 |
Default number of results returned per API response |