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

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 (optionalimage, link)logo)
        └── (links to) CommonReportResource   ← Shared asset reused across reports
ReportHistoryRecord             ← Record of a past rendering (optional)
  └── ReportPrintTask           

Each level builds on the previous.← A ReportConfigprint isjob thedispatched central entity — it connectsfrom a .jrxmlhistory record  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 taglabel you assign to report configurations to group and identify them.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 live data source when rendering a report. IfWhen a report usesconfig has a SQLconnection queryconfig defined in its .jrxml,assigned, JasperWho executes thatthe report's SQL query against this connection at render time and passesfeeds the result rows tointo JasperReportsthe report as field data.

Field	Description
connection_name	Friendly name for this connection
connection_driver	Database driver (see table below)
connection_host	HostnameIP oraddress IPof the database server
connection_port	Port (defaults— to driver standard if empty)required
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,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. ReportsWhether thatyou useneed one depends on how your report gets its data:

No connection config, no detail band — the report consists entirely of static examplecontent (e.g. a fixed-layout label). No data orneeded, no connection needed. No connection config, with detail band — the report has repeating rows, but no SQL queryquery. The row data must be delivered at allrender dotime notvia requirethe one.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 everythingall the metadata JasperWho knowsmaintains 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	WidthPage width in mm (extracted from the .jrxml on upload)
report_height	HeightPage height in mm (extracted from the .jrxml on upload)
report_query	SQL query extracted— fromdefined in JasperWho and stored in the .jrxml (if any)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 (e.g.— setfor example, setting example values,values uploador uploading resource files).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	DataJava typeclass name (e.g. java.lang.String, java.lang.Integer, Date)
parameter_required	WhetherExtracted thisfrom parameterthe mustrequired becustom suppliedproperty in the .jrxml
parameter_evaluation	Evaluation timetime, extracted from the .jrxml
parameter_example_value	ExampleExtracted valuefrom usedthe forexampleValue previewcustom renderingproperty 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 returnedof bydata that populate the report's detail band — either from an SQL query —result theor from a data thatarray populatesdelivered theat detailrender rows of a report.time.

Field	Description
field_name	Field name as defined in the .jrxml
field_data_type	DataJava typeclass name (e.g. java.lang.String, java.math.BigDecimal, Date)
field_example_value	ExampleExtracted valuefrom usedthe forexampleValue previewcustom renderingproperty (whenin nothe live DB connection is used).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 binarygraphic file assets — images, logos — that are embedded in the report templatetemplate. —They customare fonts,referenced images,in sub-reportthe .jrxml files,via andparameters similar.following the P_RESOURCE_ naming convention.

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

A resource canReportResource either beholds its own uploaded directlyfile for(resource_file_name) a specific report, or it canis be linked to a CommonReportResource. —The two are mutually exclusive: when you link a sharedresource assetto thata cancommon beresource, reusedits acrossown multiplefile reportis configurations.deleted and the common file is used in its place.

---

CommonReportResource

A CommonReportResource is a shared filegraphic 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.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, itits own file is permanently deleted. The resource slot now uses the common filefile. insteadUnlinking of its own. Updatingremoves the commonreference resourcebut automaticallydoes appliesnot restore the file — you will need to allre-upload.

linked report configurations.

---

ReportHistoryRecord

Every time a report is rendered through JasperWho — via the frontend or the API — aA ReportHistoryRecord is created. This record captures the full context of thea rendering: what was requested, what JasperReportswas responded,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 JasperReportsthe render call
report_api_response	The rawfull responseAPI fromresponse, JasperReportsstored for traceability
report_pdf_base64	Base64-encoded PDF (if stored)content
report_pdf_file_name	Filename on disk (if stored as file)
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 in the response
url	PDF stored as a file, a URL is returned
preview	Rendered for previewpreview; purposesfile onlyis not persisted
none	No PDF notoutput returned— (e.g.used for print-only flows)flows

Status values (status):

Value	Description
ok	Rendering succeeded, PDF received
render_fail	No errors reportedreported, 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 whenrepresents a renderedprint PDF isjob 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 broadcast 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	Base64Base64-encoded PDF (usedconsumed 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 abroadcastId is provided in the render request, the print task is created, itstask's ID is broadcast over WebSocket (via Laravel Reverb). upon creation. The C# print service receivescan subscribe to this event,channel, pullspick up the tasktask, data via the API, executesexecute the print job, and updatesreport 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 with which API token. was used. This information is available on all records via the withAuditwithAudit=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 for creation (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 for the last update (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 exposes severalJasperWho's runtime settingsbehaviour is controlled via environment variables. These can be setvariables 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	MaximumMax API requests per minute per token
PURGE_HISTORY_DAYS	30	Age (in days)days after which history records are purged
PURGE_PRINTTASKS_DAYS	30	Age (in days)days after which print tasks are purged
PURGE_ORPHANED_FILES_DAYS	30	Age (in days)days after which orphaned files on disk are purged
PAGINATION_DEFAULT_COUNT	25	Default number of results returned per API response