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.

Field Naming Conventions

JasperWho? uses two naming styles consistently throughout the system. Database columns and Laravel model attributes are always snake_case — for example broadcast_id, report_config_id, created_by_token_id. The API and frontend use camelCase for all request and response fields — the same fields become broadcastId, reportConfigId, createdByTokenId.

This split is consistent without exception: whenever you are working with the API or the frontend, use camelCase. Whenever you are looking at raw database records, migration files, or server-side model attributes, expect snake_case. Throughout this documentation, all field names and JSON examples follow the API convention — camelCase.

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.

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 assigned to a ReportConfig, JasperWho? executes the report's SQL query against this connection at render time and feeds the result rows into the report as field data.

Supported drivers:

Connection status is derived from connection_tested:

Network Requirements

JasperWho? establishes the database connection directly from the server it runs on. The target database must therefore be reachable from that host — ideally within the same network or at minimum via a secured private channel.

When is a ReportConnectionConfig needed?

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

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.

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.

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

ReportField

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

field_example_value is used when rendering a preview without a live database connection.

ReportResource

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

A ReportResource either holds its own uploaded file or it is linked to a CommonReportResource — never both at the same time. When linking to a common resource, the resource's 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 individually, you upload it once and link individual ReportResource records to it.

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 and controlled by the createHistoryRecord flag in the render request.

Output types (output_type):

Status values (status):

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.

Status values (status):

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.

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

Environment Configuration

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