Skip to main content

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
Back to top