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.

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 aassigned report config hasto a connection config assigned,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.

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,Scenario Connection needed? Report has no detail band — the report consists entirely ofpurely static contentlayout (e.g.No Report has a fixed-layoutdetail label). Noband, data needed,delivered novia connection needed. No connection config, with detail band — the report has repeating rows, but no SQL query. The row data must be deliveredAPI at render time No Report has a detail band and fetches data via theSQL APIYes 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,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 ExtractedRead from the required custom property in the .jrxml
    parameter_evaluation Evaluation time, extracted from the .jrxml
    parameter_example_value ExtractedRead from the exampleValue custom property in the .jrxml

    Both parameter_required and parameter_example_value are readsourced 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 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 ExtractedRead 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,images and 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 filenameFilename 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— twonever areboth mutuallyat exclusive:the whensame youtime. linkWhen a resourcelinking to a common resource, itsthe 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,report individually, 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 andis unlinking:a one-way action. 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.

    upload 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 — it isand 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).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,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:WebSocket Whenonly apply when broadcastId is provided in the render request, the print task's ID is broadcast over WebSocket (via Laravel Reverb) upon creation.request. The C# print service can subscribesubscribes to thisthat channel, pickpicks up the task, executeexecutes the print job, and report thereports status back. IfWithout noa broadcastId is provided,, the task is created silently — the print service must poll for it.

    new tasks.

    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— based on whether a token was present.present on the request.

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