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.

The Model Hierarchy

Every piece of data in JasperWho fits into a clear hierarchy. At the top sits the ReportConfig — the central entity. Everything else either belongs to it, describes it, or records what happened when it was used.

ReportContext                   ← Organisational label for grouping reports
ReportConnectionConfig          ← Optional live database connection
ReportConfig                    ← The report template + all its metadata
  ├── ReportParameter           ← Input values passed at render time
  ├── ReportField               ← Output columns from the SQL query or data payload
  └── ReportResource            ← Graphic file asset (image, logo)
        └── (links to) CommonReportResource   ← Shared asset reused across reports
ReportHistoryRecord             ← Record of a past rendering (optional)
  └── ReportPrintTask           ← A print job dispatched from a history record

ReportContext

A context is a visual label you assign to report configurations to group and identify them at a glance. 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 single context can be shared across any number of report configurations.

ReportConnectionConfig

A connection config represents a live database connection that JasperWho can use as a data source when rendering a report. When a report config has a connection config assigned, JasperWho executes the report's SQL query against this connection at render time and feeds the result rows into the report as field data.

Field	Description
`connection_name`	Friendly name for this connection
`connection_driver`	Database driver (see table below)
`connection_host`	IP address of the database server
`connection_port`	Port — required
`connection_database`	Database / schema name
`connection_username`	Username (stored encrypted)
`connection_password`	Password (stored encrypted)
`connection_test_query`	SQL query used to verify the connection
`connection_tested`	Whether the connection has been successfully tested

Supported drivers:

Driver	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 report can only be rendered with a live connection if its status is approved. JasperWho will reject render requests for reports whose connection has not been successfully tested.

When is a ReportConnectionConfig needed?

A ReportConnectionConfig is optional per ReportConfig. Whether you need one depends on how your report gets its data:

No connection config, no detail band — the report consists entirely of static content (e.g. a fixed-layout label). No data needed, no connection needed.
No connection config, with detail band — the report has repeating rows, but no SQL query. The row data must be delivered at render time via the API as a data array.
With connection config — JasperWho executes the SQL query stored in the ReportConfig against this connection automatically at render time. No manual data delivery needed.

ReportConfig

The ReportConfig is the core entity of JasperWho. It represents a single JasperReports template — the .jrxml file — together with all the metadata JasperWho maintains 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`	Page width in mm (extracted from the `.jrxml` on upload)
`report_height`	Page height in mm (extracted from the `.jrxml` on upload)
`report_query`	SQL query — defined in JasperWho and stored in the database
`report_has_detail_band`	Whether the template contains a detail band (extracted on upload)
`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

ℹ️ The SQL query is not defined in the .jrxml file. It is written and managed directly in JasperWho and stored in the database as part of the ReportConfig. The .jrxml only defines which fields the query result maps to.

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 — for example, setting example values or uploading 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`	Java class name (e.g. `java.lang.String`, `java.lang.Integer`)
`parameter_required`	Extracted from the `required` custom property in the `.jrxml`
`parameter_evaluation`	Evaluation time, extracted from the `.jrxml`
`parameter_example_value`	Extracted from the `exampleValue` custom property in the `.jrxml`

Both parameter_required and parameter_example_value are read from custom properties embedded in the .jrxml parameter definition. They can also be set manually in JasperWho after upload.

ReportField

Fields represent the columns of data that populate the report's detail band — either from an SQL query result or from a data array delivered at render time.

Field	Description
`field_name`	Field name as defined in the `.jrxml`
`field_data_type`	Java class name (e.g. `java.lang.String`, `java.math.BigDecimal`)
`field_example_value`	Extracted from the `exampleValue` custom property in the `.jrxml`

field_example_value is read from a custom property in the .jrxml field definition. It is used when rendering a preview without a live database connection.

ReportResource

Resources are graphic file assets — images, logos — that are embedded in the report template. They are referenced in the .jrxml via parameters following the P_RESOURCE_ naming convention.

Field	Description
`parameter_name`	The `P_RESOURCE_` parameter name as referenced in the `.jrxml`
`resource_file_name`	Internal filename of the directly uploaded file (nullable)
`common_report_resource_id`	FK → `CommonReportResource` (nullable)

A ReportResource either holds its own uploaded file (resource_file_name) or it is linked to a CommonReportResource. The two are mutually exclusive: when you link a resource to a common resource, its own file is deleted and the common file is used in its place.

CommonReportResource

A CommonReportResource is a shared graphic asset — a company logo, a standard header image — that multiple report configurations can reference. Instead of uploading the same file to each report, you upload it once and link individual ReportResource records to it.

Field	Description
`resource_name`	Display name
`resource_description`	Optional description
`resource_file_name`	Internal filename of the stored file

ℹ️ Linking and unlinking: When a ReportResource is linked to a CommonReportResource, its own file is permanently deleted. The resource slot now uses the common file. Unlinking removes the reference but does not restore the file — you will need to re-upload.

ReportHistoryRecord

A ReportHistoryRecord captures the full context of a rendering: what was requested, what was returned, and whether it succeeded. Creating a history record is optional — it is controlled by the createHistoryRecord flag in the render request.

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 request payload sent to the render call
`report_api_response`	The full API response, stored for traceability
`report_pdf_base64`	Base64-encoded PDF content
`report_pdf_file_name`	Filename on disk
`report_thumbnail_base64`	Base64-encoded thumbnail of the first page (generated asynchronously)
`status`	Outcome of the rendering (see below)

Output types (output_type):

Value	Description
`base64`	PDF returned inline as a Base64 string
`url`	PDF stored as a file, a URL is returned
`preview`	Rendered for preview; file is not persisted
`none`	No PDF output — used for 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 rendering completes.

ReportPrintTask

A ReportPrintTask represents a print job dispatched to a physical printer. It is always linked to a ReportHistoryRecord — you always 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 channel ID for real-time status updates (nullable)
`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-encoded PDF (consumed 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 and confirmed
`error`	Printing failed
`unknown`	Status cannot be determined

ℹ️ Real-time updates via WebSocket: When broadcastId is provided in the render request, the print task's ID is broadcast over WebSocket (via Laravel Reverb) upon creation. The C# print service can subscribe to this channel, pick up the task, execute the print job, and report the status back. If no broadcastId is provided, the task is created silently — the print service must poll for it.

Audit Trail

Every model in JasperWho tracks who created and last updated a record, and which API token was used. This information is available on all records via the withAudit=true 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 (if created via API)
`updated_at`	Timestamp of last update
`updated_by`	User ID of the last updater
`updated_by_token_id`	API token ID used (if updated via API)

The creationMethod and updateMethod fields in the API response ("Frontend" vs. "API") are derived automatically from whether a token was present.

Environment Configuration

JasperWho's runtime behaviour is controlled via environment variables in .env or as container environment variables.

Variable	Default	Description
`APP_SCHEME`	`http`	URL scheme for generated links (`http` or `https`)
`API_RATE_LIMIT_PER_MINUTE`	`10`	Max 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 per API response