Configuration and data models

VeloxFactory 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 and mails are dispatched, to how recurring work is scheduled.

Field Naming Conventions

VeloxFactory 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 VeloxFactory 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, used by reports and mails
ReportHistoryRecord                       ← Record of a past rendering (optional)
  ├── ReportPrintTask                     ← A print job dispatched from a history record
  │     └── (uses) Printer                ← Master data of the target printer
  └── ReportMailTask                      ← A mail dispatched from a history record
        ├── (uses) Mailer                 ← SMTP account the mail is sent through
        ├── (uses) MailTemplate           ← Subject and body of the mail
        └── (embeds) CommonReportResource ← Graphics placed in the mail body

ScheduledJob                              ← A recurring job: a render request, or the cleanup
  ├── (renders) ReportConfig              ← Render jobs only
  ├── (runs as) User + PersonalAccessToken  ← Owner and token a render job authenticates with
  ├── (notifies via) Mailer               ← Mailer the failure mail is sent through
  └── ScheduledJobRun                     ← Record of one execution, with trace id and result

Three of these are master data: Printer, Mailer and MailTemplate are maintained once under Configuration and then picked by name whenever a rendering is printed or mailed. They exist independently of any report.

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 VeloxFactory can use as a data source when rendering a report. When assigned to a ReportConfig, VeloxFactory 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

VeloxFactory 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 VeloxFactory. It represents a single JasperReports template (the .jrxml file) together with all the metadata VeloxFactory maintains about it.

When a .jrxml file is uploaded, VeloxFactory 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 VeloxFactory after upload.

Three parameter name prefixes carry meaning beyond the render itself:

P_SCAN_ and P_STATIC_ are what makes a report usable in Scan2Print. Everything else about the report stays the same, the prefixes are a convention, not a separate model.

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.

A common resource serves two purposes. In a report it is the file behind a P_RESOURCE_ parameter. In a mail template it is an inline graphic: the body references it by [image.<resource_name>], and at send time the file is embedded into the mail itself, not linked from a server. A resource is mail capable when it is a real PNG or JPEG with readable dimensions, which is why the name has to be unique.

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, set as a retention on the Purge Job. Thumbnails are generated asynchronously after rendering completes. Deleting a history record removes its PDF and its xlsx from disk together with the record.

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):

Printer

A Printer is master data for a physical printer. Without it, every print request had to carry the exact queue name of the print server, and everyone had to know it by heart. With it, a printer is configured once and then picked from a list.

A render request may name either the display name or the queue name, VeloxFactory resolves both. A name that matches no master data record is still accepted and passed through unchanged, so integrations written before the master data existed keep working.

Mailer

A Mailer is master data for one SMTP account. It is to mailing what a ReportConnectionConfig is to data: the credentials live in one place, are tested from the UI, and are then referenced by name.

The global MAIL_* variables of Laravel are not used by the mailing pipeline. Every mail goes through a Mailer record, registered as a runtime mail connection for the duration of the send and removed again afterwards, exactly the way a ReportConnectionConfig handles its database connection.

MailTemplate

A MailTemplate holds the subject and the body of a mail, both written once and filled with placeholders at send time.

Placeholders use the [token] syntax and cover the render ([traceId], [reportFileName]), the report, the history record, the user, the API token, the printer, every parameter ([parameters.<NAME>]), the data rows ([data.first.<FIELD>]), the current time ([now.date]), the recipients and the graphics ([image.<RESOURCE_NAME>]). The full catalog is available in the editor. An unknown token resolves to an empty string and is reported, it never fails a mail.

The four whitelabel fields are each a nullable override of a global default. Left empty, the mail uses the theme colours read from the application's own stylesheet, so a mail looks like the application without anything being configured twice.

ReportMailTask

A ReportMailTask represents one mail. Like a ReportPrintTask it belongs to a ReportHistoryRecord, you always mail a specific past rendering.

Status values (status):

ScheduledJob

A ScheduledJob is one recurring job: either a render request that fires on a crontab expression, or the consolidated cleanup that keeps the database and the disk from growing without bound. Both live in the same table and differ in their type and their payload.

A purge job carries its retentions in schedule_payload, one key per step: printTaskDays, mailTaskDays, historyDays, orphanedFileDays and runLogDays. A key set to null switches its step off.

ScheduledJobRun

A ScheduledJobRun is the record of one execution. It belongs to its schedule and is deleted with it.

Status values (status):

Audit Trail

Every model in VeloxFactory 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

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

Application

Queue & Redis

Horizon

Job Scheduler

Mailing

The standard Laravel MAIL_* keys stay untouched. They are the framework fallback and are not used for report mails.

Retention & Purge

The retentions themselves live on the Purge Job, where they are edited in the frontend or through the API. These variables supply the values the Purge Job is created with, which makes them the right place to preconfigure an instance before it is set up. Changing one afterwards has no effect on an existing schedule.