VeloxFactory

The Basics
What VeloxFactory is, how it is installed and configured, and a first look at the frontend and the API.

What is VeloxFactory?
VeloxFactory takes the JasperReports template format, JRXML, and puts a lightweight render engine of its own underneath it. The templates you already know, designed in Jaspersoft Studio as before, run on a slim, modern stack, render fast, and are one HTTP call away from a finished report. Around that engine sits a web application to manage and render them - via a clean frontend, a powerful REST API, or both.
🖥️ Built for the desk, usable on the move. VeloxFactory's views are optimised for desktop browsers, a resolution of 1600×900 or more gives the most comfortable working experience. The pages work on tablets and phones as well, which is what Scan2Print is built for: a scan station is a mobile device in the warehouse, not a workstation.
Screenshot placeholder: 
report-config.index.png
Report Config overview, the landing page after login, with context badges and thumbnails.
Where VeloxFactory Fits
JasperReports is a mature, battle-tested report engine. It produces high-quality PDFs, supports complex layouts, barcodes, images, and dynamic data - and it has been doing so reliably for decades. Integrating it directly requires a JVM on your server and Java code to drive it - which is a natural fit for Java stacks, but an overhead most PHP, Python, or C# teams prefer to avoid.
VeloxFactory keeps the template format and replaces what runs beneath it. Its render engine is lightweight and runs in pure PHP - no JVM process required on your application server - and its capabilities are exposed via a clean REST API and a management frontend. You design your report templates in Jaspersoft Studio as usual, upload them once, and from that point on, rendering is just a POST request.
POST /api/v1/report-config/A5_KanBan/render
Content-Type: application/json
Authorization: Bearer <token>
{
  "outputType": "base64",
  "parameters": { "P_ARTICLE_NUMBER": "4561287-154" },
  "data": [...],
  "createHistoryRecord": true
}
That is the entire integration.
Where It Came From
VeloxFactory was built by someone with a logistics and IT background who needed a simple, reliable way to generate article labels on demand - from whatever system was running at the time, without caring about the underlying report engine. The original idea was modest: a small API wrapper around JasperReports, nothing more.
It grew. A frontend to manage templates. Connection configs for live SQL data. History records for traceability. Print task dispatching, printer master data, a scan station. Mail delivery with its own mailers, templates and dispatch queue. A job scheduler, so the recurring work runs itself. A permission system. What started as "just get me a label PDF" is now a full suite, capable of enterprise integration on demand.
What VeloxFactory Does
At its core, VeloxFactory does six things:
Manages report templates. You upload 
.jrxml files, and VeloxFactory analyses them automatically, detecting parameters, data fields, and image resources. Everything is stored, versioned, and ready to render.
Connects to your data. VeloxFactory can execute SQL queries against live databases at render time. MySQL, MariaDB, PostgreSQL, and SQL Server are all supported. No live connection needed either - you can deliver data directly in the render request as a JSON array, which makes it equally useful for applications that already have the data in memory.
Renders on demand. A single API call produces a PDF. You choose the output format - Base64-encoded inline, a file URL, or silent output for print-only flows. Rendering is synchronous and fast.
Dispatches print jobs. Rendered PDFs can be forwarded directly to a print service via WebSocket, creating a traceable 
ReportPrintTask with status tracking. Labels off the printer, not just on the screen. Printers are maintained as master data and picked by name, and with Scan2Print a barcode scan on a phone or a handheld is enough to turn a scanned value into a printed label.
Delivers by mail. A rendering can be sent straight to whoever needs it. A render request carries an optional 
mailing segment, and VeloxFactory sends an HTML mail through a configured mailer, using a configured template, with the PDF attached and, on request, an xlsx export of the same data. Sending is synchronous or queued, every mail is logged as a traceable 
ReportMailTask.
Works on a schedule. Not every document has somebody waiting for it. The shift report that belongs in a mailbox at six in the morning, the weekly stock list, the cleanup that keeps the history from growing without bound: recurring work is configured as a schedule with a crontab expression, maintained in the frontend or through the API like everything else. A scheduled render is a complete render request, printing and mailing included, and every run is logged with its trace id.
Who It Is For
VeloxFactory is for anyone who needs to generate documents - labels, reports, delivery notes, production sheets, certificates - reliably and programmatically. The typical home is in logistics, production, and warehousing, where printing article labels, kanban cards, or shipment documents is a daily operational need and downtime is not an option.
More broadly: if your application needs to produce a PDF from structured data, and you do not want to build and maintain a report engine yourself, VeloxFactory is the answer.
Deployment
VeloxFactory is a standard Laravel application. It runs wherever PHP runs, which is nearly everywhere.
  
    
      
Scenario
      
Works?
    
  
  
    
      
Cloud VM or VPS
      
Yes
    
    
      
On-premise server
      
Yes
    
    
      
Docker container
      
Yes
    
    
      
Raspberry Pi on the shop floor
      
Yes
    
    
      
Jaspersoft Server
      
Not needed
    
  
The setup is intentionally slim. PHP 8.2 or newer, a MySQL or MariaDB database for VeloxFactory itself, and Redis for the queue that carries thumbnails, background mails and scheduled jobs, that is the stack. Two small helpers complete it: 
poppler-utils draws the report thumbnails, and Supervisor keeps the background processes running. The render engine and every other library come with the application and are installed by Composer. No application server, no JVM process to manage, no separate Jaspersoft infrastructure. The complete list is on Installing VeloxFactory.
ℹ️ Want to try it first? A live demo is available at demo.veloxfactory.dev.
Login: 
demo@veloxfactory.dev  ·  Password: 
demo

Our Vision
VeloxFactory exists because good software should not be complicated, expensive, or opaque. This page explains what we are building towards and how we think about working with the people who use it.
Simple by Design
The goal behind VeloxFactory has always been the same: take a powerful but complex technology and make it accessible to teams who just need it to work. Not teams with a dedicated Java architect. Not teams with a six-figure infrastructure budget. Teams with a problem to solve and a deadline to meet.
That philosophy shapes every decision in VeloxFactory, from the API design to the frontend workflows. Concepts should be easy to grasp. Setup should be fast. Day-to-day use should feel obvious, even for someone who has never heard of JasperReports.
Reliable and Performant
Simple does not mean limited. VeloxFactory is designed to handle real production workloads - in logistics, on the shop floor, in warehouses where a label printer needs to respond in milliseconds and cannot afford to fail during a shift.
The architecture reflects this. The stack is intentionally slim - no unnecessary layers, no bloat. Rendering is synchronous and fast. The application runs comfortably on modest hardware, including single-board computers deployed directly in production environments.
When VeloxFactory is running, it runs. That is the expectation we build to.
No Lock-In
VeloxFactory is built exclusively on open-source components. There is no proprietary cloud dependency, no mandatory subscription, no remote kill switch. You run it where you want - on your own server, in your own cloud account, on a machine on your shop floor - and it stays yours.
The report templates you design in Jaspersoft Studio are standard 
.jrxml files. The database you connect to is your own. The PDFs it produces belong to you. VeloxFactory is infrastructure you own and control, not a service you rent.
Grows With You
Most customers start with a single, focused use case - generating an article label, a delivery note, a production sheet. VeloxFactory handles that out of the box. But as requirements evolve, the platform grows with them.
History records for traceability. Print task dispatching via WebSocket. A scan station for the warehouse floor. Mail delivery with its own templates and dispatch queue. Multi-report management with a structured permission system. API access for any system that can make an HTTP call. None of these need to be in scope on day one, but they are all there when the time comes.
Beyond the built-in capabilities, VeloxFactory is extended on request. If a workflow requires something specific, it can be built in. Licenses include continued development and updates, the software does not freeze at the point of purchase.
A Real Partner
VeloxFactory is not sold by a faceless vendor with a tiered support portal. It is built and maintained by someone with deep hands-on experience in logistics IT, system integration, and shop floor environments, and that experience is available directly to every customer.
This means practical help where it matters: rolling out the application, connecting it to existing ERP or WMS systems, adapting report templates to operational realities, and making sure the implementation actually works in the environment it needs to run in, not just in a demo.
The goal is not a one-time sale. It is a long-term working relationship with customers who have real problems and need a partner who understands them.
The Full Picture
To put it plainly: VeloxFactory is powerful software at a reasonable price, built on open foundations, designed to be simple to operate, and backed by someone who will pick up the phone.
If that sounds like what you need, welcome.

Installing VeloxFactory
VeloxFactory is a standard Laravel application. The setup is intentionally slim - pull the repository, install dependencies, configure the environment, migrate the database. A standard installation is up and running in under 30 minutes.
What You Don't Need
Before listing what is required, it is worth being explicit about what is not:
No Java - the render engine is pure PHP. No JVM, no Java runtime, no Java SQL drivers.
No Node.js / npm / Vite - the frontend assets are pre-built and bundled with the repository.
No Jaspersoft Server - VeloxFactory is entirely self-contained.
No Docker - optional for the database only, not required for the application itself.
System Requirements
Requirement
Notes
PHP >= 8.2
Required extensions: 
ctype, 
curl, 
fileinfo, 
filter, 
hash, 
mbstring, 
openssl, 
pcntl, 
pdo, 
pdo_sqlite, 
posix, 
redis, 
session, 
simplexml, 
tokenizer, 
zip, 
gd, 
xml. For report database connections, additionally: 
pdo_mysql (MySQL / MariaDB), 
pdo_pgsql (PostgreSQL). SQL Server is listed separately below.
Composer
PHP dependency manager - getcomposer.org
MySQL or MariaDB
VeloxFactory's own application database. A Docker container works fine if no local instance is available.
Redis
Required for the queue driver (Laravel Horizon). Install via 
apt install redis-server or run as a Docker container. The 
php-redis extension must also be installed: 
apt install php-redis. See Background Job Processing for details.
poppler-utils
Provides 
pdftoppm, used for generating report thumbnails. Install via 
apt install poppler-utils.
Supervisor
Keeps the three background processes running: Horizon (queue workers), Reverb (WebSocket server), and the Scheduler. See Background Job Processing for the full Supervisor configuration.
SMTP access
Only required for report mailing. The server has to reach the SMTP host of each configured mailer, usually on port 587 or 465. Credentials are not set up here, they are maintained as Mailers inside the application.
Apache2 or nginx
Optional reverse proxy. Not required for local or development setups.
php-sqlsrv / pdo_sqlsrv
Only required when connecting to Microsoft SQL Server as a report data source. Not needed otherwise.
Bundled Dependencies
The following components are bundled with VeloxFactory, no separate installation required:
Component
Purpose
VeloxFactory render engine
Pure PHP render engine, our maintained fork of JasperPHP - parses 
.jrxml and generates PDFs via TCPDF. Installed automatically by Composer.
Laravel Horizon
Redis-backed queue manager with built-in dashboard. Manages worker pools for thumbnail generation, background mail dispatch and the nightly purge jobs. Installed automatically by Composer.
PhpSpreadsheet
Builds the xlsx export that a report mailing can attach next to the PDF. Needs the PHP extensions 
zip, 
gd and 
xml. Installed automatically by Composer.
Log Viewer
In-browser Laravel log viewer for monitoring application logs.
Scribe
Generates the interactive API documentation from source annotations.
Material Design Icons
Icon set used throughout the frontend.
Ace Editor
In-browser code editor for writing SQL queries.
Logo & Color Concept
Visual identity by sinister-labs.
Jaspersoft Studio 6.21.5
Desktop IDE for designing 
.jrxml report templates. Installed separately on the designer's machine, not on the server. Download here.
First Setup
php artisan setup:base prepares the storage folders and creates the administrator 
admin@veloxfactory.dev. Its password is generated at random and printed to the console exactly once, it is not stored anywhere in clear text. Copy it down. The first sign-in forces a password change before anything else in the instance is usable.
Nothing below storage is executed
Rendered documents, report templates and resource files are served as static files from 
storage/app/public. The web server must never execute anything in that directory. The repository ships 
storage/app/public/.htaccess for Apache; add the matching directive to your virtual host:
<Directory /var/www/veloxfactory/storage/app/public>
    php_admin_flag engine off
    Options -Indexes -ExecCGI
    AllowOverride All
</Directory>
For nginx:
location ^~ /storage/ {
    location ~ \.(php|phar|phtml)$ { deny all; }
    add_header X-Content-Type-Options "nosniff" always;
}
Administrative routes
The Log Viewer is reachable at 
admin/log-viewer (configurable through 
LOG_VIEWER_ROUTE) and requires 
global:admin. The API reference generated by Scribe is at 
/docs and requires 
global:use-api.
Deployment Options
VeloxFactory can be deployed in two ways: self-hosted on your own infrastructure, or fully managed and operated by kiwi software. Both options deliver identical functionality, the choice depends on your team's operational preferences and existing infrastructure.
Self-Hosted
You run VeloxFactory on your own servers. The infrastructure footprint is intentionally small - no Java runtime, no application server, no container orchestration required. A single modest Linux VPS covers all but the most demanding workloads.
Component
Minimum
Recommended
Notes
VeloxFactory server (Linux)
1 vCPU, 1 GB RAM
2 vCPU, 4 GB RAM
A Hetzner CX22 (2 vCPU, 4 GB RAM, 40 GB NVMe) is more than sufficient for most deployments. Any comparable entry-level VPS or on-premises Linux server works equally well.
Disk
10 GB
40 GB
Application and report thumbnails. Scale with report volume and history retention period.
VeloxFactory Print Service (Windows)
Windows 10/11 or Windows Server 2019 or newer, x64, .NET 10 Desktop Runtime, with the target printers installed
Runs headless from the Windows Task Scheduler under its own service account, with an optional window for setup and monitoring. Low memory and CPU use; in most deployments an existing Windows PC on the shop floor or in the office serves as the print host. No dedicated hardware required. See Installation and updates.
ℹ️ MySQL and VeloxFactory can share the same VM for small to medium deployments. A dedicated database server is only worth considering when multiple VeloxFactory instances share one database, or under very high render throughput.
Managed Hosting
If you prefer not to manage infrastructure yourself, VeloxFactory can be hosted and operated for you. Instances run exclusively in Germany on Hetzner hardware - reliable, fast, and GDPR-compliant by location. Updates, monitoring, and backups are handled on your behalf.
Managed hosting works well for most use cases. Depending on your network connection to the hosting location, render requests may see slightly higher latency compared to a locally deployed instance, typically not noticeable, but worth considering for high-frequency, latency-sensitive workloads such as real-time label printing on the shop floor.
For managed hosting enquiries, get in touch directly.

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 scheduled 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.
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 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.
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. VeloxFactory will reject render requests for reports whose connection has not been successfully 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.
⚠️ Do not expose your database to the public internet. Configuring a publicly accessible database (or opening firewall ports to make one reachable) is a significant security risk and is strongly discouraged. If VeloxFactory and your database run in separate networks, use an encrypted VPN tunnel instead: WireGuard or OpenVPN are both well-suited for this purpose.
When is a ReportConnectionConfig needed?
A 
ReportConnectionConfig is optional per 
ReportConfig. Whether you need one depends on how your report gets its data:
Scenario
Connection needed?
Report has no detail band (purely static layout)
No
Report has a detail band, data delivered via API at render time
No
Report has a detail band and fetches data via SQL
Yes
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.
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 VeloxFactory 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 VeloxFactory 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, 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.
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
Read from the 
required custom property in the 
.jrxml
parameter_evaluation
Evaluation time, extracted from the 
.jrxml
parameter_example_value
Read from the 
exampleValue custom property in the 
.jrxml
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:
Prefix
Meaning
P_RESOURCE_
The parameter holds a graphic file asset, VeloxFactory creates a 
ReportResource for it
P_SCAN_
The parameter is filled by a barcode scan in Scan2Print
P_STATIC_
The parameter is preset once per Scan2Print session and stays untouched between scans
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
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
Read from the 
exampleValue custom property in the 
.jrxml
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.
Field
Description
parameter_name
The 
P_RESOURCE_ parameter name as referenced in the 
.jrxml
resource_file_name
Filename of the directly uploaded file (nullable)
common_report_resource_id
FK → 
CommonReportResource (nullable)
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.
Field
Description
resource_name
Display name, unique, and at the same time the placeholder token used in a mail body
resource_description
Optional description
resource_file_name
Internal filename of the stored file
resource_mime_type
Detected mime type, filled on upload
resource_width / 
resource_height
Pixel dimensions, read from the file
resource_display_width
Optional width the graphic is rendered with in a mail
resource_alt_text
Alternative text for the mail graphic
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.
ℹ️ Linking is a one-way action. When a 
ReportResource is linked to a 
CommonReportResource, its own file is permanently deleted. Unlinking removes the reference but does not restore the file, you will need to re-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 and 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 of the PDF on disk
report_excel_file_name
Filename of the xlsx export on disk, written when a mailing asked for one (nullable)
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, 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.
Field
Description
report_config_id
FK → 
ReportConfig
report_history_record_id
FK → 
ReportHistoryRecord
printer_id
FK → 
Printer (nullable, set when the printer was picked from the master data)
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
Created, waiting for the print service
printed
Successfully printed and confirmed
error
Printing failed
unknown
Status cannot be determined
ℹ️ Real-time updates via WebSocket only apply when 
broadcastId is provided in the render request. The C# print service subscribes to that channel, picks up the task, executes the print job, and reports status back. Without a 
broadcastId, the task is created silently, the print service must poll for new tasks.
Printer
A 
Printer is master data for a physical printer. A printer is configured once and then picked from a list, so nobody has to know the exact queue name of the print server by heart.
Field
Description
printer_display_name
The name people see, for example 
Warehouse Label 01. Unique, 3 to 50 characters
printer_name
The queue name on the print server, for example 
WH-LABEL-01. This is what the print service receives. Unique
printer_type
label-printer, 
a4-printer, 
mfc-printer or 
digital-printer. Descriptive, it drives icon and filter
printer_location
Where the machine stands, for example 
Hall 2, Shipping (nullable)
printer_broadcast_id
WebSocket channel of the print service instance that serves this printer (nullable)
printer_description
Free note, for example the loaded media (nullable)
printer_is_active
Inactive printers keep working in existing configurations but are no longer offered in pickers
The master data is a convenience, not a requirement. A render request may name a printer by its display name or by its queue name, VeloxFactory resolves both and fills in the broadcast channel. A name that matches no master data record is passed through to the print service unchanged, so an integration can route straight to any queue of the print server by its name, without a 
Printer record.
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.
Field
Description
mailer_name
Unique name used to reference the mailer in a request
mailer_transport
Transport, 
smtp by default
mailer_host / 
mailer_port
SMTP server and port
mailer_scheme
smtp, 
smtps or empty for the transport default
mailer_username / 
mailer_password
Credentials, stored encrypted
mailer_from_address / 
mailer_from_name
Sender of every mail sent through this mailer
mailer_reply_to
Optional reply-to address
mailer_timeout / 
mailer_local_domain
Optional transport details
mailer_rate_limit_per_minute
Max mails per minute, empty means the window is not enforced
mailer_rate_limit_per_hour
Max mails per hour, 
500 by default
mailer_rate_limit_per_day
Max mails per day, empty means the window is not enforced
mailer_is_active
Inactive mailers are not offered and are refused by the API
mailer_tested
Whether a test mail has been sent successfully
mailer_description
Free note
ℹ️ The three rate limit windows are independent and all have to allow a send. Providers cap differently: Office 365 counts per minute, most hosters per hour, Gmail per day. A blocked send is not lost, it is queued and goes out when the window opens.
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.
Field
Description
mail_template_name
Unique name used to reference the template in a request
mail_template_subject
Subject line, placeholders allowed
mail_template_body_html
HTML body, written in a rich text editor, placeholders allowed. Buttons and callouts are stored as 
data-mail-button and 
data-mail-callout markers
mail_template_header_color
Optional override of the header bar colour, also used for table headers, the default button background and the Info callout border
mail_template_header_line_color
Optional override of the colour of the line beneath the header
mail_template_hide_header_line
Hides the line beneath the header
mail_template_body_color
Optional override of the body background
mail_template_hide_logo
Hides the logo in the header
mail_template_logo_resource_id
FK → 
CommonReportResource, an own logo for this template (nullable)
mail_template_footer_text
Optional override of the global footer text, placeholders allowed
mail_template_is_active
Inactive templates are not offered and are refused by the API
mail_template_description
Free note
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 whitelabel fields are each an override of a global default. Left empty or off, the mail uses the theme colours read from the application's own stylesheet, a dark header bar with a line in the primary colour beneath it, 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.
Field
Description
report_history_record_id
FK → 
ReportHistoryRecord (nullable if no history record was created)
mailer_id
FK → 
Mailer
mail_template_id
FK → 
MailTemplate
trace_id
Unique identifier for this mail run
recipients_to / 
recipients_cc / 
recipients_bcc
Resolved address lists
mail_subject
The rendered subject, placeholders already resolved
mail_body_html
The rendered body, stored so the UI can show what was actually sent
attachment_pdf_file_name
The PDF on the history disk, always 
<trace id>.pdf
attachment_excel_file_name
The xlsx on the history disk, always 
<trace id>.xlsx
attachment_pdf_name
The name the PDF carries as an attachment of the mail
attachment_excel_name
The name the xlsx carries as an attachment of the mail
send_async
Whether the mail was queued instead of sent synchronously
dispatch_after
Set when the rate limit pushed the send into the future
sent_at
Timestamp of the successful send
error_message
Error detail if sending failed
status
Current mail status (see below)
Status values (
status):
Value
Description
pending
Created, not sent yet, or waiting for a rate limit window
sent
Handed over to the SMTP server successfully
error
Sending failed
unknown
Status cannot be determined
ℹ️ A mail task never owns a file. The PDF and the xlsx belong to the history record, stay downloadable from it and are deleted with it. The two attachment name columns only say what the files are called inside the mail. Mail tasks have their own retention on the Purge Job, independent of the history records.
The address columns hold what was actually used: a recipient given as a placeholder is stored resolved, so the mail task shows the addresses the mail went to.
ScheduledJob
A 
ScheduledJob is one scheduled job: either a render request, 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. Either kind fires on a crontab expression or once at a fixed date and time.
Field
Description
schedule_name
Display name, unique
schedule_description
Optional description
schedule_type
render or 
purge
schedule_cron
Five-field crontab expression. Empty means the schedule never fires on its own and can only be run manually
schedule_timezone
Timezone the expression and the single date are evaluated in. Empty means the application timezone
schedule_run_at
Date and time of a single run. Set in place of a cron expression, never beside one
schedule_deactivate_after_run
Whether the schedule sets itself inactive once its single run is done
schedule_is_active
An inactive schedule is never dispatched
report_config_id
FK → 
ReportConfig, render jobs only
schedule_payload
JSON. Render jobs: the render request body. Purge jobs: the retention map
owner_user_id
FK → 
User, the user a render job runs as
owner_token_id
FK → 
PersonalAccessToken, the token a render job authenticates with
error_mailer_id
FK → 
Mailer, the mailer the failure mail goes through (nullable)
error_recipients_to / 
error_recipients_cc / 
error_recipients_bcc
Address lists of the failure mail, plain addresses without placeholders
schedule_last_run_at
When the schedule last fired
schedule_next_run_at
When it fires next. Indexed, this is what the minute tick selects on. Empty once a single run has happened
schedule_last_status
Status of the most recent run
ℹ️ The owner and the token are references, not copies. Both are foreign keys with a delete restriction, so a user or a token that a schedule runs with cannot be removed while the schedule exists. A revoked token or a deactivated owner does not delete anything, it parks the schedule and is recorded as a skipped run.
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.
Field
Description
scheduled_job_id
FK → 
ScheduledJob, cascading delete
trace_id
Identifier of this run, the same id the rendering and its mail carry
status
Outcome of the run (see below)
trigger
schedule for a run the cron fired, 
manual for Run now
started_at / 
finished_at / 
duration_ms
Timing of the run
run_as_user_id
The user the run authenticated as, kept even after the schedule's owner changed
report_history_record_id
FK → 
ReportHistoryRecord the run produced (nullable)
response_status
HTTP status the internal render call answered with
result_summary
JSON summary: what a render returned, or how many records each purge step deleted
error_message
Error detail if the run failed
error_mail_sent
Whether a failure mail went out for this run
error_mail_suppressed
How many failure mails the throttle held back
Status values (
status):
Value
Description
running
The run started and has not finished yet
success
Everything the run was asked to do went through
warning
The main work succeeded, something attached to it did not, for example the mail
error
The run failed
skipped
The run was not executed, for example because the owner is inactive or the token revoked
ℹ️ The history record is referenced, never owned. 
report_history_record_id is nulled when the record is deleted, so the history retention stays free to clean up what a run produced. The run log itself is cleaned up by the Purge Job.
User
The account a person or an integration signs in with. Only the field that governs the first sign-in is listed here, the permissions themselves are described in Meet the frontend.
Field
Description
password_change_required
Set when an account must change its password before it can use the instance. 
setup:base sets it on the administrator it creates
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.
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, based on whether a token was present on the request.
Security Log
Alongside 
jobs, VeloxFactory writes a 
security channel to 
storage/logs/security/, kept for 90 days. It records sign-ins and failed attempts, sign-outs, password changes, permission changes and the creation and revocation of API tokens.
Environment Configuration
VeloxFactory's runtime behaviour is controlled via environment variables in 
.env or as container environment variables.
Application
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
PAGINATION_DEFAULT_COUNT
25
Rows per page in the lookups of the frontend
API_PER_PAGE_DEFAULT
25
Records per page of an API list endpoint when the request sends no 
perPage
API_PER_PAGE_MAX
100
Largest 
perPage an API list endpoint accepts, a larger value is answered with 422
Security
Variable
Default
Description
SANCTUM_EXPIRATION
525600
Lifetime of an API token in minutes, one year by default. Applies to tokens that already exist
DB_TRUST_SERVER_CERTIFICATE
false
Accept a self-signed certificate on a report database. Only for closed networks
DB_ENCRYPT
true
Encrypted connection to the report database
OUTBOUND_HOST_ALLOWLIST
empty
Comma separated hosts that Report Connection Configs and Mailers may point at. Empty means everything except loopback and link-local
LOG_VIEWER_ROUTE
admin/log-viewer
URL path of the Log Viewer
Queue & Redis
Variable
Default
Description
QUEUE_CONNECTION
database
Queue driver (must be set to 
redis for Horizon)
REDIS_CLIENT
phpredis
Redis client library (
phpredis required)
REDIS_HOST
127.0.0.1
Redis server hostname or IP
REDIS_PORT
6379
Redis server port
REDIS_PASSWORD
null
Redis password (leave 
null if not set)
REDIS_QUEUE_RETRY_AFTER
360
Seconds before a reserved job on the 
redis connection is handed to another worker. Must stay above the longest worker timeout
REDIS_SCHEDULER_QUEUE_RETRY_AFTER
1860
The same for the 
redis-scheduler connection, which carries the long-running scheduled jobs
Horizon
Variable
Default
Description
HORIZON_PATH
horizon
URL path for the Horizon dashboard
HORIZON_PREFIX
derived from 
APP_NAME
Redis key prefix for all Horizon data
HORIZON_DOMAIN
-
Optional custom domain for the Horizon dashboard
Job Scheduler
Variable
Default
Description
SCHEDULER_CATCHUP_GRACE_MINUTES
60
A due run older than this is dropped instead of fired late, for example after the scheduler process was down
SCHEDULER_RUN_LOCK_SECONDS
1800
How long one run may hold its schedule's lock before another run may start
SCHEDULER_ERROR_MAIL_THROTTLE_MINUTES
60
At most one failure mail per schedule within this window
SCHEDULER_PREVIEW_COUNT
5
How many upcoming run dates the cron preview shows
PURGE_SCHEDULER_RUNS_DAYS
90
Retention of the run log, written into the Purge Job when it is created
Mailing
Variable
Default
Description
MAIL_LOGO_RESOURCE
-
Name of a mail capable 
CommonReportResource, embedded inline in the mail header
MAIL_LOGO_URL
-
Fallback used when 
MAIL_LOGO_RESOURCE is empty: an absolute, publicly reachable URL. Empty falls back to the application name as text
MAIL_FOOTER_TEXT
Sent automatically by VeloxFactory.
Footer of every mail, overridable per template
MAIL_RATE_LIMIT_PER_MINUTE
0
Default minute limit for a newly created mailer. 
0 means not enforced.
MAIL_RATE_LIMIT_PER_HOUR
500
Default hour limit for a newly created mailer
MAIL_RATE_LIMIT_PER_DAY
0
Default day limit for a newly created mailer
MAIL_THROTTLE_FALLBACK_TO_QUEUE
true
A throttled synchronous send is queued instead of answered with an error
MAIL_MAX_ASSET_SIZE_KB
2048
Maximum size of a graphic that can be embedded into a mail
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.
Variable
Default
Description
PURGE_HISTORY_DAYS
30
Age in days after which history records are deleted. 
-1 creates the step switched off.
PURGE_PRINTTASKS_DAYS
30
Age in days after which print tasks are deleted. 
-1 creates the step switched off.
PURGE_MAILTASKS_DAYS
30
Age in days after which mail tasks are deleted. 
-1 creates the step switched off.
PURGE_ORPHANED_FILES_DAYS
30
Age in days after which orphaned files on disk are deleted. 
-1 creates the step switched off.

Meet the frontend
VeloxFactory comes with a built-in web frontend that gives you full access to every feature without writing a single line of code. It is built with Laravel Livewire, a reactive framework that delivers a dynamic, app-like feel while keeping everything server-rendered. No separate JavaScript build, no SPA complexity.
Screenshot placeholder: 
report-config.index.png
Report Config overview, the landing page after login, with context badges and thumbnails.
Navigation
After logging in you land directly on the Report Configs overview, the central workspace. Dedicated scan users without edit rights for report configurations land on Scan2Print instead. All other sections are reachable from the main navigation.
Section
What you manage here
Report Configs
Your report templates, the heart of VeloxFactory
Report History Records
Every past rendering with status, payload, and PDF
Report Print Tasks
Print jobs dispatched to the print service
Mail Queue
Every mail that was sent or is waiting to go out, see Report Mailing
Job Scheduler
Recurring renders and the cleanup run, plus the log of every run, see The Job Scheduler
Scan2Print
Mobile scan station that turns every barcode scan into a print job, see Scan2Print: Printing labels by scanning
Report Contexts
Organisational labels and visual tags for reports
Report Connection Configs
Live database connections for SQL-driven reports
Common Report Resources
Shared graphic assets, used by reports and as inline graphics in mails
Printers
Master data for your physical printers, see Printers
Mailers
Master data for your SMTP accounts, see Mailers
Mail Templates
Subject, body and whitelabeling of your mails, see Mail Templates
Users
User accounts and API token management
The last seven entries are grouped under Configuration in the main navigation. They are master data you set up once and then pick by name everywhere else.
The Lookup Pattern
Every section opens with a list view, powered by a Livewire Lookup component. These views work the same way across all sections, so once you know one, you know them all.
Screenshot placeholder: 
report-config.index.filtered.png
Report Config overview with the filter bar open and active filter badges.
Full-Text Search
A search bar at the top filters records instantly as you type, no page reload, no submit button. Depending on the section, the search covers names, descriptions, file names, and query text.
Column Filters
Each list view offers contextual filter dropdowns tailored to the entity. For Report Configs, for example, you can filter by Context, Data Adapter, Creator, or date ranges for creation and last update. Active filters are indicated by a badge count on the respective dropdown so you always see at a glance which filters are in play.
Pagination
Results are paginated. The default page size is controlled by the 
PAGINATION_DEFAULT_COUNT environment variable (default: 25). See Configuration and Data Models for all available environment settings.
Persistent Filters and Paging
Every list view remembers its state. The search term, all column filters (checkboxes, dropdown selections, date ranges) and the current page are stored in your session as soon as you change them. You can open a record, switch to another section and come back later, the list shows exactly the same filters and the same page as before.
The state is kept separately for each list view. Filters set on History Records do not affect Report Configs or any other section.
To start over, click the reset button of the respective list view, the dark button with the curved arrow icon between the search bar and the green Filter button. It clears the search term and all filters of this view and returns to the first page. All other views keep their filters.
ℹ️ Filters are stored per user session. They survive page reloads and navigation, but are cleared on logout or when the session expires. Filters are never shared with other users or other browser sessions.
Working with Report Configs
The Report Config section has the richest set of actions and is where most of your day-to-day work happens.
Screenshot placeholder: 
report-config.edit.png
Report Config edit view with parameters, fields and resources.
Uploading a Template
Report templates are designed in Jaspersoft Studio (compatible version: 6.21.5) and exported as 
.jrxml files. Once you have a 
.jrxml ready, you upload it to VeloxFactory to create a new Report Config. VeloxFactory immediately analyses the file and automatically creates all associated Parameters, Fields, and Resources, based on what is defined in the template. You do not need to add these manually.
After upload you review the auto-generated records: set example values where missing, assign a Data Adapter if the report uses SQL, and upload any resource files that were detected.
Managing Parameters, Fields, and Resources
Parameters, Fields, and Resources each have their own section within the Report Config edit view. You can edit example values, mark parameters as required, upload resource files, or link a resource to a Common Report Resource, all from the same screen.
Screenshot placeholder: 
report-resource.edit.png
Report Resource edit view with the file upload and the link to a Common Report Resource.
Generating Previews
Once all example values are set and all resource files are uploaded, you can generate a preview rendering directly from the edit view. VeloxFactory renders the report using the stored example values and stores the result as a preview image and thumbnail on the Report Config.
Rendering from the Frontend
You can trigger a full render directly from the frontend, without touching the API. A render dialog lets you fill in parameter values, choose an output type, and optionally dispatch a print job or a mail in the same step. The result is shown inline and logged as a History Record if desired.
Screenshot placeholder: 
generate-pdf.create.png
Generate PDF page with the parameter inputs and the output settings.
Report Connection Configs
When creating or editing a Connection Config, the form includes a Test Connection button. Use it before saving, a connection must be in status approved before VeloxFactory will use it for rendering. An untested or failed connection will cause render requests to be rejected.
Screenshot placeholder: 
report-connection-config.edit.png
Report Connection Config edit form with the Test Connection button.
Report History Records
The History Records section gives you a full log of every rendering that was saved. For each record you can see the status, the exact parameters and data that were submitted, the raw JasperReports response, and, if the rendering succeeded, the resulting PDF.
From a History Record you can:
Download the PDF directly to your browser, and the xlsx export if the record has one
Trigger a print job, creates a new Print Task for this specific rendering and dispatches it to the print service
Send it by mail, opens a dialog for mailer, template, recipients and attachments and creates a new Mail Task
Screenshot placeholder: 
report-history-record.show.png
Report History Record detail page with status, payload, PDF preview and the actions.
ℹ️ Downloads follow the read permission. Downloading a rendered PDF, an xlsx export, a report template or a resource file requires the read permission for that resource. Being signed in is not enough.
Report Print Tasks
The Print Tasks section shows all dispatched print jobs and their current status. For each task you can inspect the target printer, number of copies, and any error messages if printing failed.
If a task ended up in error state, you can reset it, the task returns to pending and the print service will pick it up again.
Screenshot placeholder: 
report-print-task.index.png
Report Print Task overview with status badges, printer and the reset action.
Mailing
A rendered document can be mailed as well as printed. Three sections work together, and all three behave like every other list view described above.
Mailers hold your SMTP accounts: host, port, credentials, sender address and the dispatch rate limits. The form has a Test Mailer button and a Send test mail action, the same idea as Test Connection on a Connection Config. A mailer has to be active before it is offered anywhere.
Mail Templates hold subject and body. The body is written in a built-in rich text editor, so no HTML knowledge is needed. A button opens the placeholder catalog, a searchable table of every token the template can use, each one copyable with a click. A preview shows the finished mail exactly as a recipient will see it, including the colours and the logo, which can be overridden per template.
Mail Queue lists every mail task with recipients, subject, attachments, mode and status. Opening one shows the mail that was actually sent, rendered in place. From there a mail can be repeated: a dialog lets you correct the mailer or the recipients before it goes out again, so a mail sent to the wrong address is fixed rather than cloned.
Screenshot placeholder: 
mail-template.edit.png
Mail Template edit view with the rich text editor, the placeholder button and the whitelabel toggles.
Mailing itself is never configured here. It is requested per rendering, in the Generate PDF page, in the Scan2Print settings, in the mail dialog of a History Record, in a render job of the Job Scheduler, or in the 
mailing segment of a render request. The three sections above only provide the building blocks.
Screenshot placeholder: 
mailing.history-record-modal.png
The mail dialog of a Report History Record with mailer, template, recipients and attachments.
ℹ️ Full detail is on the dedicated pages: Report Mailing, Mailers and Mail Templates.
Scheduling
Work that repeats has its own section. Job Scheduler lists every schedule with its type, its crontab expression, the next and the last run, and how that run ended. A Run Log button opens the full history of every run of every schedule, each with its trace id.
Creating a schedule starts with the type, a render job or the cleanup run, and the form follows from there. The expression is entered either in a guided mode with frequency, time and weekday pickers or as plain crontab syntax; both write the same field, and the next five run times are shown while you type. A render job additionally takes the report, an API token, the output and print settings, and the same parameter and data row tables as the Generate PDF page, here with a switch per field for entering a placeholder such as 
[now.date] instead of a fixed value.
Run now starts a schedule immediately without moving its next slot, which is how a new one is tried before it is switched on.
Screenshot placeholder: 
scheduler.overview.png
The Job Scheduler overview with type, cron expression, next run, last run and status per schedule.
ℹ️ Full detail is on the dedicated pages: The Job Scheduler, Render Jobs and The Purge Job.
Users and API Tokens
User accounts are managed under the Users section, accessible to administrators only. Each user can hold one or more named API tokens, which grant API access under that user's identity.
From the user edit view you can:
Create a new token and copy it immediately after generation (it is only shown once)
Revoke any existing token with immediate effect
Reset another user's password, or change your own after confirming the current one
Screenshot placeholder: 
user.edit1.png
User edit view, account data and API token management.
Screenshot placeholder: 
user.edit2.png
User edit view, the permission sections.
Screenshot placeholder: 
create-token.modal.png
Create API token dialog, the token is shown once.
⚠️ Copy your token immediately after creation. VeloxFactory only displays the token value once. If you lose it, you will need to revoke the old token and create a new one.
⚠️ Tokens are issued and revoked here, never through the API. A request that authenticates with an API token cannot create or revoke tokens and is answered with 
403 API tokens can only be managed from the web interface. That is deliberate: a token that could issue another one would survive its own revocation, and revoking a leaked token would not actually lock it out.
Permissions
Every user in VeloxFactory has a set of permissions that controls what they can see and do, both in the frontend and via the API. Since both use the same underlying controllers, a permission that restricts an action in the frontend restricts the exact same action via API, and vice versa. There is no way to grant API-only or frontend-only access to a resource.
Permissions fall into two categories: global and per-resource.
Global permissions:
Permission
Effect
global:admin
Full access to everything, including user management. Only an administrator may grant or withdraw permissions, activate or deactivate accounts, and manage other users' API tokens
global:use-api
Required for every API request. Without it, each call answers 
403 This user is not permitted to use the API. Also allows managing one's own API tokens in the web interface
Per-resource permissions, available for each of the following resources: 
report-config, 
report-connection-config, 
report-context, 
report-history-record, 
report-print-task, 
report-mail-task, 
common-report-resource, 
printer, 
mailer, 
mail-template, 
scheduled-job:
Permission
Effect
<resource>:full
Full read/create/update/delete access to this resource
<resource>:read
View records only
<resource>:create
Create new records
<resource>:update
Edit existing records
<resource>:delete
Delete records
global:admin always implies full access to all resources and overrides any per-resource setting.
scheduled-job:* also covers the run log. Changing or starting a render job is limited to its owner and to administrators, because it acts with the owner's permissions; reading it is not.
Feature permissions:
Permission
Effect
scan2print:use
Access to Scan2Print. Implicitly includes 
report-config:read, 
report-print-task:read and 
:create, 
report-history-record:create and 
:update
scheduled-job:create
Creating a schedule means rendering, printing and mailing with it, so it implicitly includes 
report-config:read, 
report-print-task:create, 
report-mail-task:create and 
report-history-record:create and 
:update. 
scheduled-job:full does the same
ℹ️ Permissions are administrator territory. Users can edit their own name and e-mail address, but not their own permissions. The permission section is not shown to them, and a request that carries a permission list is answered with the user's current set instead. The same applies to activating and deactivating an account. VeloxFactory also refuses to let the last remaining administrator give up 
global:admin or be deactivated, so an instance can never end up without one.
ℹ️ API token permissions are inherited from the user. A token does not have its own permission set, it acts with exactly the permissions of the user it belongs to, evaluated on every single request. Withdrawing a permission takes effect on the next call, there is nothing to re-issue. Deactivating a user revokes all of their tokens at once, and tokens expire after the period configured in 
SANCTUM_EXPIRATION (one year by default).
Signing in
The login form answers every failed attempt the same way, with 
Invalid credentials. Whether the address belongs to an account, whether that account is deactivated and whether the password was wrong are deliberately indistinguishable, so the form cannot be used to find out which addresses exist on an instance.
Attempts are limited to five per minute, counted per source address and per e-mail address. Beyond that the form answers 
429 Too Many Requests until the minute is over. Successful and failed sign-ins, sign-outs, password changes, permission changes and token operations are written to a dedicated 
security log channel.
ℹ️ Changing your own password needs the current one. An administrator resetting someone else's password does not. Either way, every API token of that account is revoked afterwards, so a password change really does end all access that was granted before it.
Frontend vs. API - What is the Difference?
The short answer: there is no feature difference. The frontend calls the exact same controller methods as the API. Everything you can do in the UI, you can also automate via API.
The frontend is optimised for interactive, human-driven workflows, exploring reports, reviewing history records, testing connections. The API is the right choice when you want to integrate rendering into external systems, automate repetitive tasks, or process results programmatically.
ℹ️ Ready to explore the API? See Meet the API for authentication, query parameters, and a practical render example.

Meet the API
VeloxFactory ships with a fully capable REST API, and it is not an afterthought. Every action you can perform in the frontend can also be performed via the API, because the frontend and the API share the same controller methods. There is no separate implementation, no feature gap, no second-class citizen.
This makes the API a genuine alternative to the UI, not just an integration bolt-on. Automate report rendering in your CI pipeline, trigger prints from your ERP, manage report configurations programmatically, have VeloxFactory run the whole thing on a schedule, all with the same logic that powers the frontend you already know.
ℹ️ For the full endpoint reference including all parameters and response schemas, explore the live demo API documentation at demo.veloxfactory.dev.
Login: 
demo@veloxfactory.dev  ·  Password: 
demo
Authentication
The API uses token-based authentication via Laravel Sanctum. Every request must include a Bearer token in the 
Authorization header.
Authorization: Bearer your-api-token
⚠️ Every API request requires 
global:use-api. The permission is checked on each call, not only when a token is issued. A token whose user does not hold it is answered with 403, even if the token itself is valid and the user has the resource permissions.
Tokens are issued and revoked per user in the user management section of the frontend. A request authenticated by a token cannot create or revoke tokens, so a leaked token cannot renew itself and revoking it actually locks it out. A revoked token is rejected immediately, there is no grace period.
{
  "success": false,
  "errors": ["This API token has been revoked."],
  "status": 401
}
The audit trail records which token was used for every create and update operation across all models, so every API action is fully traceable.
Authentication Errors
Status
Message
When
401
This user account is disabled.
The account behind the token was deactivated
401
This API token has been revoked.
The token was revoked, or every token of the user was revoked by a password change or a deactivation
401
Token expired
The token is older than 
SANCTUM_EXPIRATION
403
This user is not permitted to use the API.
The user is missing 
global:use-api
403
API tokens can only be managed from the web interface.
A token tried to create or revoke a token
Base URL
All API v1 endpoints are prefixed with:
/api/v1/
Referencing Records
Wherever a request points at another record, it accepts either the numeric ID or the unique name of that record. These two are the same call:
POST /api/v1/report-config/12/render
POST /api/v1/report-config/Shift Report/render
The same holds inside request bodies, for report contexts, connection configs, mailers, mail templates and schedules alike, so a payload stays readable without a lookup table of IDs. A Report History Record is addressed by its ID or by its trace id, which is what makes a trace id worth carrying through your own systems.
ℹ️ A value of digits only is always read as an ID. That is why a name cannot consist of digits only. VeloxFactory refuses such a name when a record is created or renamed, so 
4711 is never ambiguous.
Response Structure
All API responses follow a consistent envelope format.
Success, list endpoint:
{
  "success": true,
  "count": 25,
  "data": [ { ... }, { ... } ],
  "links": {
    "first": "https://your-instance/api/v1/report-print-task?status=pending&page=1",
    "last": "https://your-instance/api/v1/report-print-task?status=pending&page=3",
    "prev": null,
    "next": "https://your-instance/api/v1/report-print-task?status=pending&page=2"
  },
  "meta": {
    "pagination": {
      "currentPage": 1,
      "lastPage": 3,
      "perPage": 25,
      "total": 61,
      "from": 1,
      "to": 25,
      "hasMorePages": true,
      "path": "https://your-instance/api/v1/report-print-task"
    }
  },
  "status": 200
}
Success, single record:
{
  "success": true,
  "count": 1,
  "data": { ... },
  "links": { "first": null, "last": null, "prev": null, "next": null },
  "meta": {
    "pagination": {
      "currentPage": 1,
      "lastPage": 1,
      "perPage": 1,
      "total": 1,
      "from": 1,
      "to": 1,
      "hasMorePages": false,
      "path": "https://your-instance/api/v1/report-print-task/256"
    }
  },
  "status": 200
}
Error:
{
  "success": false,
  "errors": ["Descriptive error message"],
  "meta": {},
  "status": 404
}
Every success response that carries 
data has the same shape, whether it returns a list, a single record, a freshly created record or a render result. A client parses one envelope for every endpoint.
count is the number of records in 
data: the records on the current page for a list, 
1 for a single record.
links point to the first, last, previous and next page. A link that does not exist is 
null. Responses that are not paginated have all four links 
null.
meta.pagination describes the page, see Pagination. A response that is not paginated reports exactly one page.
meta carries further contextual information next to 
pagination, such as the 
traceId of a render run or the 
mailing result.
Error responses have no 
links and no 
pagination block.
Pagination
All list endpoints (
GET /user, 
GET /report-config, 
GET /report-print-task and every other 
GET on a resource without an id) return their records page by page. Two query parameters control the page:
Parameter
Type
Default
Description
page
integer
1
Page to return, starting at 
1.
perPage
integer
25
Records per page, 
1 to 
100.
The values of the 
pagination block:
Field
Meaning
currentPage
The page in this response.
lastPage
Number of the last page, at least 
1.
perPage
Page size used for this response.
total
Number of all records matching the request, across all pages.
from / 
to
Position of the first and last record of this page within 
total, 
null on an empty page.
hasMorePages
true as long as a next page exists.
path
URL of the endpoint without query string.
Filters such as 
status, 
type or 
isActive apply before the records are split into pages, so 
total counts the filtered result. The links in 
links carry all query parameters of the request, a client follows 
links.next until it is 
null and keeps its filters on every page.
A page behind the last one returns 
200 with an empty 
data array. A 
page below 
1, a 
perPage above 
100 or a non-numeric value returns 
422, and so does a filter value the endpoint does not know, for example 
status=foo on 
GET /report-print-task.
To read every record, request 
perPage=100 and follow 
links.next. Every page is a request of its own and counts against the rate limit.
The two placeholder catalogs (
GET /mail-template/placeholders, 
GET /scheduled-job/placeholders) are not paginated and always return one page.
The page size default and maximum are set with 
API_PER_PAGE_DEFAULT and 
API_PER_PAGE_MAX, see Configuration and Data Models. A default above the maximum is reduced to the maximum.
ℹ️ 
limit is a deprecated alias of 
perPage and will be removed in a future version. 
perPage takes precedence when both are sent, and 
limit=0 returns the maximum page size. There is no request that returns all records at once. A response to a request that uses 
limit without 
perPage carries the header 
Deprecation: true and a note in 
meta.messages.
Query Parameters
Most 
GET endpoints and the render endpoint share a common set of query parameters that control what is included in the response. They are additive, combine them freely.
Parameter
Type
Default
Description
page, 
perPage
integer
1, 
25
Page and page size on list endpoints, see Pagination.
withRelations
boolean
false
Include related models (e.g. parameters, fields, resources on a ReportConfig).
recursiveRelations
boolean
false
Include nested relations within relations.
withMedia
boolean
false
Include Base64-encoded file content, previews, and thumbnails.
withAudit
boolean
false
Include the audit segment on each record (timestamps, users, token, method).
Example, retrieve a single report config with all relations, media, and audit data:
GET /api/v1/report-config/1?withRelations=true&withMedia=true&withAudit=true
Audit Segment
When 
withAudit=true is set, every record in the response carries an 
audit block:
"audit": {
  "createdAt": "2026-05-08 11:26:30",
  "createdByUser": 2,
  "createdByToken": null,
  "creationMethod": "Frontend",
  "updatedAt": "2026-05-08 13:31:35",
  "updatedByUser": 1,
  "updatedByToken": "Postman",
  "updateMethod": "API"
}
creationMethod and 
updateMethod are derived automatically, 
"API" when a token was used, 
"Frontend" when the action came through the UI. A run of a scheduled job fills these exactly like a direct call does, with the owner of the schedule and the token it runs with.
Render-Specific Request Body
The render endpoint (
POST /api/v1/report-config/{id}/render) accepts the following fields in the request body (JSON).
Field
Type
Required
Description
outputType
string
✅
How to return the PDF: 
base64, 
url, 
preview, or 
none
createHistoryRecord
boolean
✅
Whether to persist a 
ReportHistoryRecord for this render
createPrintTask
boolean
✅
Whether to create a 
ReportPrintTask after rendering
printerName
string
if 
createPrintTask
Name of the target printer
useExampleValues
boolean
 
Use stored example values instead of supplying parameters manually
parameters
object
 
Key-value map of parameter names to values
resourceOverrides
object
 
Per-render override for 
P_RESOURCE_* image parameters, keyed by parameter name. A path has to point at a readable file inside the resources folder, a URL has to be 
https://, or the image is supplied as a Base64 upload. See Rendering with our powerful API for the full reference.
data
array
 
Array of data rows, for reports without a live DB connection
numberOfCopies
integer
 
Number of print copies (default: 1)
broadcastId
string
 
WebSocket channel ID, triggers real-time status updates for the print task
traceId
string
 
Custom trace ID; auto-generated as UUID if omitted. Unique across all history records
laconicResponse
boolean
 
Strip the response to just the PDF output (see below)
mailing
object
 
Send the rendering by mail once it succeeded: mailer, mail template, recipients, attachments and sync or queued dispatch. See Report Mailing for the full reference.
⚠️ Output type 
none requires 
createPrintTask: true. Rendering without any output and without a printer to send it to is rejected, and a 
mailing segment does not take the place of the print task. 
preview and 
mailing are refused together as well, a preview render deletes its own file immediately and has nothing to attach.
Laconic Responses
By default, a render response is fully populated, it includes the echoed input, the PDF output, the linked 
ReportConfig, the created 
ReportHistoryRecord, and the 
ReportPrintTask and 
ReportMailTask if applicable. In high-frequency or bandwidth-sensitive scenarios, add 
laconicResponse=true to strip everything down to just the PDF output.
The Same Body on a Schedule
This body is also what a render job of the Job Scheduler stores. A request you have tested here can be dropped into the 
payload of a schedule unchanged, minus 
traceId, which every run generates for itself. See Render Jobs.
Rate Limiting
The API enforces a configurable rate limit per token. The default is 10 requests per minute. When the limit is exceeded:
{
  "success": false,
  "message": "Too many requests! The current rate limiting is 10 requests per minute.",
  "status": 429
}
The limit is adjusted via the 
API_RATE_LIMIT_PER_MINUTE environment variable, see Configuration and Data Models.
Endpoints Overview
Resource
Available operations
User
List, show, create, update, change password, enable/disable, create/revoke tokens (web interface only)
ReportContext
List, show, create, update, delete
ReportConnectionConfig
List, show, create, update, delete, test connection
CommonReportResource
List, show, create, update, delete
ReportConfig
List, show, create, update, delete, update resources / parameters / fields, generate previews, render
ReportResource
Link / unlink CommonReportResource
ReportHistoryRecord
List, show, create, update, delete, print, mail
ReportPrintTask
List, show, create, update, delete, set printed, set status
ReportMailTask
List, show, create, delete, repeat
Printer
List, show, create, update, delete
Mailer
List, show, create, update, delete, test configuration, send test mail
MailTemplate
List, show, create, update, delete, placeholder catalog, preview
ScheduledJob
List, show, create, update, delete, run now, cron preview, placeholder catalog
ScheduledJobRun
List, show, delete
A Practical Example: The Full Render Response
A render call returns a 
ReportRendering object. By default it is fully populated, you see the input you sent, the PDF output, and the linked records that were created.
{
  "success": true,
  "count": 1,
  "data": {
    "model": "ReportRendering",
    "traceId": "a3f9c1d2-4e87-4b2a-9f1c-d3e8b7a20f61",
    "input": {
      "parameters": {
        "P_ARTICLE_NUMBER": "4561287-154"
      },
      "data": null
    },
    "output": {
      "reportPdfFileName": "a3f9c1d2-4e87-4b2a-9f1c-d3e8b7a20f61.pdf",
      "reportPdfBase64": "JVBERi0xLjQ...",
      "reportUrl": null
    },
    "reportConfig": { "..." },
    "reportHistoryRecord": { "..." },
    "reportPrintTask": null
  },
  "links": { "first": null, "last": null, "prev": null, "next": null },
  "meta": {
    "traceId": "a3f9c1d2-4e87-4b2a-9f1c-d3e8b7a20f61",
    "pagination": {
      "currentPage": 1,
      "lastPage": 1,
      "perPage": 1,
      "total": 1,
      "from": 1,
      "to": 1,
      "hasMorePages": false,
      "path": "https://your-instance/api/v1/report-config/12/render"
    }
  },
  "status": 200
}
Add 
laconicResponse=true and the response collapses to just 
output, no echoed input, no embedded related records. Ideal for automated pipelines that only need the PDF.

Try it out
The demo instance gives you a fully functional VeloxFactory environment, pre-loaded with report templates and example data. Everything you can do in a production setup you can do here, with one exception: print tasks do not reach a real printer.
Screenshot placeholder: 
report-config.index.png
Report Config overview, the landing page after login, with context badges and thumbnails.
Access
Demo URL: demo.veloxfactory.dev
Login: 
demo@veloxfactory.dev  ·  Password: 
demo
The demo account has full access to all report data, Report Configs, History Records, Print Tasks, Mail Tasks, Connection Configs, Contexts, Common Resources, Printers, Mailers and Mail Templates. It can also generate and use API tokens. User management is not available.
Guided Tour
Work through these steps in order for a complete first look at VeloxFactory.
Step 1 - Browse the Report Configs
After logging in you land on the Report Configs list. This is the central workspace. Each card shows a thumbnail preview of the report and its context badge.
Use the search bar to filter by name, or use the dropdown filters to narrow by context or data adapter. Try typing part of a report name, the list updates instantly, no page reload.
Screenshot placeholder: 
report-config.index.filtered.png
Report Config overview with the filter bar open and active filter badges.
Step 2 - Explore a Report Config
Click any report to open its detail view. Here you can inspect:
Parameters - the inputs the report expects at render time, with their data types and example values
Fields - the data columns that populate the report body
Resources - image assets embedded in the template (logos, icons)
Preview - the rendered thumbnail, generated from the stored example values
Scroll through the sections to get a feel for what VeloxFactory extracts from a 
.jrxml file automatically on upload.
Screenshot placeholder: 
report-config.edit.png
Report Config edit view with parameters, fields and resources.
Step 3 - Render a Report from the Frontend
From within a Report Config, click the Generate PDF button. A dialog opens with pre-filled parameter values (taken from the example values stored on the config). You can edit any of them before rendering.
Select an output type, Base64 is fine for a quick look, and click Generate PDF. VeloxFactory processes the request and shows the resulting PDF inline within seconds. No API call needed, no setup required.
Screenshot placeholder: 
generate-pdf.create.png
Generate PDF page with the parameter inputs and the output settings.
Step 4 - Check the History Record
Navigate to Report History Records. Your render from Step 3 appears at the top of the list (if you left 
createHistoryRecord enabled in the dialog). Open it to see the full log: the exact request payload, the API response, the rendered PDF, and a thumbnail.
From here you can download the PDF directly, trigger a reprint, which creates a new Print Task, or send the document by mail, which creates a new Mail Task.
Screenshot placeholder: 
report-history-record.show.png
Report History Record detail page with status, payload, PDF preview and the actions.
Try It Yourself
Once you have completed the tour, these are good next things to explore on your own.
Upload Your Own Template
If you have a 
.jrxml file designed in Jaspersoft Studio, you can upload it directly to the demo. Go to Report Configs → Create, attach the file, and let VeloxFactory analyse it. Within seconds, all parameters, fields, and resources are detected and listed automatically.
ℹ️ Use Jaspersoft Studio 6.21.5. This is the version compatible with VeloxFactory's render engine. Download it from the Jaspersoft Community. Reports created with a significantly newer version may use features the render engine does not support.
After upload, set any missing example values, upload resource files if needed, and click Generate Preview to produce a thumbnail. The report is then ready to render.
Call the API Directly
The demo account has API access enabled. To get a token, open the user menu in the top right corner and go to Account Settings → API Tokens, copy it immediately, it is only shown once.
With the token in hand, render any report with a single HTTP request:
curl -X POST \
  https://demo.veloxfactory.dev/api/v1/report-config/{reportName}/render \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "outputType": "base64",
    "useExampleValues": true,
    "createHistoryRecord": true
  }'
Replace 
{reportName} with the 
report_name of any config from the list (visible in the detail view). The 
useExampleValues flag tells VeloxFactory to use the stored example values instead of requiring you to pass parameters and data manually, ideal for a first test.
The response contains the rendered PDF as a Base64 string and a trace ID you can look up in History Records.
Send a Report by Mail
Mailing is the second way a rendering leaves VeloxFactory. Two mailers are waiting for you under Configuration.
  
    
      
Mailer
      
What it is for
    
  
  
    
      
Demo Log Mailer
      
Writes every mail into the application log instead of sending it. Ready to use, and the safe way to follow the whole path from render to mail task without anything leaving the machine.
    
    
      
Demo SMTP Mailer
      
The starting point for a real send. It carries placeholder values, 
smtp.example.com on port 587 with scheme 
smtp, user and sender 
change-me@example.com, and it is inactive so nobody picks it before it works.
    
  
To send for real, open the SMTP mailer, replace host, port, credentials and sender with the data of a mailbox you own, send a test mail from the form, and set it active. Then write a Mail Template with a subject and a body. The editor has a placeholder button that lists every token the template can use.
With a mailer and a template in place, open any History Record and click Mail, or switch on Send results via Mail in the Output Settings of the Generate PDF page. The mail goes out with the PDF attached, and optionally with an xlsx export of the same data. Every mail shows up in the Mail Queue with its status, its recipients and the body that was actually sent.
Explore Print Tasks
When rendering via the frontend or API, enable the print task option and provide any printer name (e.g. 
demo-printer). VeloxFactory creates a 
ReportPrintTask record with status pending. Since no print service is connected to the demo, the task stays pending, but you can inspect the full record and see how status tracking works. Completed print tasks are purged automatically after a configurable retention period.
Demo Limitations
  
    
      
What
      
Behaviour in the demo
    
  
  
    
      
Print tasks
      
Created and traceable, but no real printer connected, tasks remain pending. Completed tasks are purged automatically.
    
    
      
Mail dispatch
      
Mailers and Mail Templates can be created freely and a mailing can be configured end to end. The log mailer records the mail instead of sending it; whether a real mail is delivered depends on the SMTP account you enter, the demo has no mailbox of its own.
    
    
      
Live SQL connections
      
Connection Configs can be created and tested, but no external databases are reachable from the demo environment.
    
    
      
User management
      
The demo account does not have admin rights, user accounts and permissions cannot be managed.
    
    
      
Data persistence
      
Uploaded templates, history records, and other data may be reset periodically.
    
  
ℹ️ Ready to go further? See Meet the Frontend for a full walkthrough of the UI, or Meet the API for complete API documentation.

Open Source Attribution
VeloxFactory and its companion VeloxFactory Print Service are built on open source software. We are grateful to the authors and contributors of the following packages.
VeloxFactory
Package
License
Description
laravel/framework
MIT
The Laravel PHP framework routing, ORM, queues, and the application foundation.
laravel/horizon
MIT
Queue manager and dashboard for the Redis queues that run thumbnails, mail dispatch and the nightly purge jobs.
laravel/reverb
MIT
First-party Laravel WebSocket server used to broadcast print task events in real time.
laravel/sanctum
MIT
API token authentication for the VeloxFactory REST API.
laravel/tinker
MIT
REPL for the Laravel application.
livewire/livewire
MIT
Full-stack component framework for the VeloxFactory frontend.
opcodesio/log-viewer
MIT
In-browser Laravel log viewer.
knuckleswtf/scribe
MIT
Automatic API documentation generator.
phpoffice/phpspreadsheet
MIT
Spreadsheet library used to build the xlsx export that a report mailing can attach alongside the PDF.
quilhasoft/jasperphp
MIT
Pure-PHP JasperReports renderer. The VeloxFactory render engine is our maintained fork of this project, extended with a Java expression interpreter, Java-style formatting, full style support and numerous layout fixes. The original MIT license and copyright notice are retained.
tecnickcom/tcpdf
LGPL-3.0
PDF library used by the render engine to write the PDF files, including barcodes.
VeloxFactory Print Service
The VeloxFactory Print Service 2.0 runs on .NET 10 (Windows Desktop Runtime) and bundles the following packages.
Package
License
Description
PDFtoImage
MIT
Ships the native PDFium library; used for page sizes and previews.
PDFium
BSD 3-Clause
Google's PDF engine, draws every page directly onto the printer.
Microsoft.Extensions.Hosting / Http
MIT
Generic host, dependency injection, options and HTTP client factory.
Microsoft.Data.Sqlite
MIT
SQLite access for the job journal, outbox, statistics and log buffer in 
state.db. SQLite itself is public domain.
Serilog
Apache 2.0
Structured logging to rolling files, console and the Windows event log (
Serilog.Extensions.Hosting, 
Serilog.Sinks.File, 
Serilog.Sinks.Console, 
Serilog.Sinks.EventLog, 
Serilog.Formatting.Compact).
TaskScheduler
MIT
Creates and reads the Windows scheduled task of the headless service.
CommunityToolkit.Mvvm
MIT
MVVM base for the window.
MaterialDesignThemes
MIT
Material Design controls and themes for the WPF window.
ScottPlot.WPF
MIT
Charts on the statistics page.
SkiaSharp
MIT
2D graphics library used by ScottPlot and PDFtoImage.
Material Symbols Rounded
Apache 2.0
Icon font of the window, the same icons as in the VeloxFactory frontend.

Get VeloxFactory
Interested in using VeloxFactory in your own environment? Get in touch, we'll figure out the right setup together.
Contact
  
    
      
Name
      
Benjamin Fischer
    
    
      
E-Mail
      
bfischer@kiwi-software.dev
    
    
      
Website
      
www.kiwi-software.dev
    
  
What to Expect
Drop a short message explaining your use case, what you need to generate, how often, and whether you'd prefer self-hosted or managed. You'll hear back within one business day.
If you want to explore the product first, the live demo is open:
ℹ️ Want to try it first? A live demo is available at demo.veloxfactory.dev.
Login: 
demo@veloxfactory.dev  ·  Password: 
demo
Smarter Code. Frischer Blick.

Report Configurations
From a JRXML in Jaspersoft Studio to a Report Config in VeloxFactory, including the data adapters.

Creating reports in Jaspersoft Studio
VeloxFactory renders reports defined as 
.jrxml files — the native format of JasperReports. These files are designed in Jaspersoft Studio, a free desktop IDE built specifically for this purpose. This page explains how to set up a 
.jrxml file so that VeloxFactory can analyse it correctly, register all its parts, and render it reliably.
ℹ️ Which bands, elements and expressions does VeloxFactory support? VeloxFactory renders with its own pure-PHP render engine, not with the Java JasperReports library. The supported feature set, the expression syntax and the formatting rules are listed in Render engine: supported features and expressions.
Jaspersoft Studio
Jaspersoft Studio is an Eclipse-based visual report designer. You use it to lay out the report template — define what data goes where on the page, how it is formatted, and which inputs the report expects. The resulting 
.jrxml file is then uploaded to VeloxFactory, which takes over everything from there: storing it, analysing it, connecting it to a data source, and rendering it on demand.
ℹ️ Use version 6.21.5. This is the version compatible with VeloxFactory. Download it from the Jaspersoft Community. Reports created with a significantly newer version may use features that VeloxFactory's render engine does not support.
The division of responsibilities between Jaspersoft Studio and VeloxFactory is clear:
Jaspersoft Studio defines the layout, the parameters, the fields, and the visual design of the report.
VeloxFactory manages the SQL query, the data connection, and the actual rendering at runtime.
This means you will see a 
<queryString> element in Jaspersoft Studio — but as explained below, you leave it empty. VeloxFactory supplies the query separately.
The Report Name
Every Jaspersoft Studio project has a Report Name — the 
name attribute on the root 
<jasperReport> element. This is not just a filename: VeloxFactory reads it directly from the 
.jrxml on upload and stores it as 
report_name on the 
ReportConfig.
<jasperReport ... name="A5_KanBan" ...>
This name must be unique across all report configurations in VeloxFactory. If you try to upload a 
.jrxml whose report name already exists, the upload will be rejected. The same applies to the file name itself.
⚠️ Set a descriptive, unique report name in Jaspersoft Studio before uploading. You can change it in Jaspersoft Studio via File → Report Properties → Report Name, or directly in the XML. Changing it after upload requires re-uploading the file.
Parameters
Parameters are input values passed into the report at render time. They are used inside the report layout via 
$P{PARAMETER_NAME} expressions — for example to display a customer name in the title, filter by a date range, or pass a document number into a barcode expression.
You define parameters in Jaspersoft Studio via the Report Inspector → Parameters section. Each parameter has a name and a Java data type.
Custom Properties: exampleValue and required
VeloxFactory reads two custom properties from each parameter definition: 
exampleValue and 
required. These are not standard Jaspersoft features — they are custom 
<property> elements you add manually to the parameter in the 
.jrxml. VeloxFactory's analyser (
JasperFunctions::analyzeReportFile) extracts them on upload.
Property
Value type
Purpose
exampleValue
string
A representative value used when rendering a preview of the report without real data. Also pre-fills the parameter input in the frontend render form.
required
boolean (
true / 
false)
Whether this parameter must be provided in every render request. VeloxFactory rejects render requests that are missing a required parameter.
Both properties can also be set or updated manually in VeloxFactory after upload — they do not have to come from the 
.jrxml. But embedding them in the file means they are automatically picked up every time the report is uploaded or re-uploaded.
To add these properties in Jaspersoft Studio, open the parameter in the Report Inspector, switch to the Properties panel, and add a new custom property via the green + button.
Supported Data Types
VeloxFactory supports the following Java class types for parameters. The type determines how the input field is rendered in the frontend and how the value is handled at render time.
Java class
Frontend input
Notes
java.lang.String
Text field
General-purpose text input
java.lang.Boolean
Toggle
Rendered as a checkbox/toggle switch
java.lang.Short
Integer input
Range: −32,768 to 32,767
java.lang.Integer
Integer input
Range: −2,147,483,648 to 2,147,483,647
java.lang.Long
Integer input
64-bit integer
java.lang.Float
Decimal input
Single-precision floating point
java.lang.Double
Decimal input
Double-precision floating point
java.math.BigDecimal
Decimal input
Arbitrary-precision decimal; preferred for monetary values
java.sql.Date
Date picker
Date only (no time)
java.util.Date
Date picker
Date only (no time)
java.sql.Time
Time picker
Time only (HH:mm)
java.sql.Timestamp
Date + time picker
Combined date and time (datetime-local)
Fields
Fields represent the data columns that populate the report's detail band — the repeating section that produces one row of output per data record. Each field corresponds to a column in the SQL query result (when using a live connection) or a key in the data array delivered at render time via the API.
You define fields in Jaspersoft Studio via the Report Inspector → Fields section. In the report layout, you reference them via 
$F{FIELD_NAME} expressions inside text fields in the detail band.
Custom Property: exampleValue
Fields support one custom property: 
exampleValue. It works the same way as for parameters — a representative value used when rendering a preview of the report without a live data connection. VeloxFactory collects these example values and assembles a synthetic data row from them for preview rendering.
You add 
exampleValue to a field the same way as for parameters: open the field in the Report Inspector, go to the Properties tab, and add the custom property.
ℹ️ Set meaningful example values for all fields. Without them, VeloxFactory cannot generate a preview or thumbnail for the report configuration. The values do not need to be real data — they just need to be type-compatible and representative enough to make the preview look sensible.
Fields support the same Java data types as parameters (see the table above). Use the type that matches the column type your SQL query or data array will produce.
Using Parameters as SQL Variables
When a 
ReportConfig has a 
ReportConnectionConfig assigned, VeloxFactory executes the SQL query defined in the report configuration against that live database connection. Parameters passed in the render request are available as named bindings inside that query — using the standard 
:parameterName syntax from Laravel's Eloquent database layer.
This means you can reference any parameter directly in your SQL to filter, sort, or limit the result set:
SELECT
    article_number  AS articleNumber,
    description,
    moq,
    delivery_time   AS deliveryTime,
    supplier,
    barcode
FROM articles
WHERE article_number = :P_ARTICLE_NUMBER
In this example, 
:P_ARTICLE_NUMBER is replaced at query execution time with the value of the 
P_ARTICLE_NUMBER parameter from the render request. The binding is handled natively by PDO — values are passed as proper prepared statement parameters, not interpolated as strings.
ℹ️ Only parameters that are actually referenced in the query are bound. VeloxFactory scans the query for 
:name placeholders before execution and silently drops any parameters that are not needed. Passing extra parameters in the render request will never cause a query error.
The parameter name in the query binding must match the parameter name exactly as defined in the 
.jrxml — including case. For example, a parameter named 
P_ARTICLE_NUMBER in the report must be referenced as 
:P_ARTICLE_NUMBER in the SQL query.
You can use as many parameters as needed across 
WHERE, 
ORDER BY, 
LIMIT, or any other clause that accepts a value binding. Note that named bindings cannot be used for identifiers like table or column names — only for values.
Resources (Images and Logos)
If your report contains images — a company logo, a header graphic, a product photo — these are defined as resource parameters in the 
.jrxml. VeloxFactory detects them automatically on upload and creates a 
ReportResource record for each one.
The naming convention is strict: every resource parameter must start with 
P_RESOURCE_ and must have the Java class 
java.lang.String. At render time, VeloxFactory replaces the parameter value with the actual file path of the uploaded image on the server.
<!-- Resource parameter: logo image -->
<parameter name="P_RESOURCE_LOGO" class="java.lang.String">
    <defaultValueExpression><![CDATA["C:/VeloxFactory/Logo_Dark.png"]]></defaultValueExpression>
</parameter>
In the report layout, you then bind this parameter to an image element:
<image>
    <reportElement x="460" y="100" width="84" height="50" uuid="..."/>
    <imageExpression><![CDATA[$P{P_RESOURCE_LOGO}]]></imageExpression>
</image>
The 
<defaultValueExpression> is used only in Jaspersoft Studio for design-time preview purposes. VeloxFactory ignores it at render time — it always uses the uploaded file path instead. You can point it to a local file on your design machine.
⚠️ Resource parameters are not treated as regular parameters in VeloxFactory. They do not appear in the Parameters section — they appear in the Resources section. In the vast majority of render requests you do not pass them at all; VeloxFactory fills them in automatically from the linked resource file.
ℹ️ Exception: per-render overrides. A render request can optionally supply 
resourceOverrides to swap a resource parameter's image for that single call only — a local path, a remote 
http(s):// URL, or a Base64 upload — without changing the report configuration's linked default. This is an opt-in override on top of the linked resource described above, not a replacement for it: a default file or 
CommonReportResource still has to be linked before the report can render at all. See Rendering with our powerful API for the full reference.
After uploading the 
.jrxml, you must go to the Resources section of the report configuration in VeloxFactory and upload the actual image file for each detected resource. A report cannot be rendered until all its resources have files assigned.
The Detail Band
The detail band is the repeating section of the report — the part that outputs one row per data record. If your report displays a list of items, a table, or any kind of repeating structure, it lives in the detail band.
VeloxFactory checks whether a detail band is present when analysing the 
.jrxml:
If a detail band exists, VeloxFactory expects data to be provided at render time — either via a live SQL connection or via the 
data array in the API request.
If no detail band exists, the report is treated as a static layout — no data is needed, only parameters.
⚠️ If you add a detail band, it must contain at least one text field element that uses a field expression (
$F{...}). A detail band that exists but displays no field data will be rejected on upload. VeloxFactory uses the presence of text fields in the band as a basic integrity check.
Reports without a detail band are perfectly valid — they are useful for documents like cover pages, summary sheets, or any report whose content is entirely driven by parameters rather than repeated rows.
The SQL Query
Jaspersoft Studio has a built-in 
<queryString> element where you would normally write the SQL query for the report. In VeloxFactory, this element is ignored. The SQL query is instead defined and stored directly in VeloxFactory as part of the 
ReportConfig — not in the 
.jrxml file.
This means you should leave the 
<queryString> empty when creating a 
.jrxml for VeloxFactory:
<queryString>
    <![CDATA[]]>
</queryString>
You write the actual SQL query in VeloxFactory after uploading the report, in the Query field of the report configuration. This design keeps the query where it can be managed, versioned, and changed without touching the report template file.
The query result columns must match the field names you defined in the 
.jrxml. For example, if your report has a field named 
articleNumber, your SQL query must return a column called 
articleNumber.
The Data Adapter
Jaspersoft Studio uses Data Adapters to connect to a live database so you can preview your report during design. This is entirely a design-time feature — the data adapter you configure in Jaspersoft Studio has no effect in VeloxFactory and is not stored in the 
.jrxml.
At render time, VeloxFactory always uses its own internal array-based adapter to pass data to the render engine. Whether that data comes from an SQL query executed against a 
ReportConnectionConfig or from a data array in the API request, VeloxFactory always handles the data handoff itself.
You still benefit from configuring a data adapter in Jaspersoft Studio during development — it lets you see a realistic preview while designing the layout. Just be aware that the adapter configuration stays local to your machine.
Annotated Example
The following is a complete, minimal 
.jrxml that demonstrates everything discussed on this page. It is the actual 
A5_KanBan report included in the VeloxFactory demo. Inline comments explain each relevant element.
<?xml version="1.0" encoding="UTF-8"?>
<!-- Created with Jaspersoft Studio version 6.21.5 -->
<jasperReport
    xmlns="http://jasperreports.sourceforge.net/jasperreports"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="..."
    name="A5_KanBan"         <!-- Report Name — becomes report_name in VeloxFactory. Must be unique. -->
    pageWidth="595"          <!-- Page dimensions in Jasper pixels (1px = 1/72 inch).              -->
    pageHeight="842"         <!-- VeloxFactory converts these to mm on upload.                       -->
    ...>
    <!-- ═══════════════════════════════════════════════════════════════════
         RESOURCE PARAMETER
         Name starts with P_RESOURCE_ and class is java.lang.String.
         VeloxFactory detects this as a resource (image/logo), not a parameter.
         The defaultValueExpression points to a local file for Studio preview —
         VeloxFactory replaces it at render time with the uploaded file path.
         ═══════════════════════════════════════════════════════════════════ -->
    <parameter name="P_RESOURCE_LOGO" class="java.lang.String">
        <defaultValueExpression><![CDATA["C:/VeloxFactory/Logo_Dark.png"]]></defaultValueExpression>
    </parameter>
    <!-- ═══════════════════════════════════════════════════════════════════
         REGULAR PARAMETER
         P_ARTICLE_NUMBER is a user-supplied input value passed at render time.
         exampleValue  → used for preview rendering and pre-fills the frontend form.
         required      → omitting this parameter in a render request will cause a 422 error.
         ═══════════════════════════════════════════════════════════════════ -->
    <parameter name="P_ARTICLE_NUMBER" class="java.lang.String">
        <property name="exampleValue" value="4561287-154"/>
        <property name="required"     value="true"/>
    </parameter>
    <!-- ═══════════════════════════════════════════════════════════════════
         QUERY STRING — leave empty.
         The SQL query is defined in VeloxFactory, not here.
         ═══════════════════════════════════════════════════════════════════ -->
    <queryString>
        <![CDATA[]]>
    </queryString>
    <!-- ═══════════════════════════════════════════════════════════════════
         FIELDS
         Each field maps to a column in the SQL result or a key in the data array.
         exampleValue → used for preview rendering when no live data is available.
         ═══════════════════════════════════════════════════════════════════ -->
    <field name="articleNumber" class="java.lang.String">
        <property name="exampleValue" value="1868745-584"/>
    </field>
    <field name="description" class="java.lang.String">
        <property name="exampleValue" value="Packing Carton Size 1 - 200x150x50mm"/>
    </field>
    <field name="moq" class="java.lang.Integer">
        <property name="exampleValue" value="250"/>
    </field>
    <field name="deliveryTime" class="java.lang.String">
        <property name="exampleValue" value="3 Days"/>
    </field>
    <field name="supplier" class="java.lang.String">
        <property name="exampleValue" value="Ninghao Packaging"/>
    </field>
    <field name="barcode" class="java.lang.String">
        <property name="exampleValue" value="5698532145712"/>
    </field>
    <!-- ═══════════════════════════════════════════════════════════════════
         DETAIL BAND
         The repeating section — one iteration per data row.
         Must contain at least one <textField> using a $F{...} expression,
         otherwise VeloxFactory rejects the file on upload.
         The image element uses $P{P_RESOURCE_LOGO} — VeloxFactory resolves
         this to the uploaded resource file at render time.
         ═══════════════════════════════════════════════════════════════════ -->
    <detail>
        <band height="167" splitType="Stretch">
            <!-- Field values referenced via $F{...} expressions -->
            <textField>
                <textFieldExpression><![CDATA[$F{articleNumber}]]></textFieldExpression>
            </textField>
            <textField>
                <textFieldExpression><![CDATA[$F{description}]]></textFieldExpression>
            </textField>
            <!-- Resource image: bound to the P_RESOURCE_LOGO parameter -->
            <image>
                <imageExpression><![CDATA[$P{P_RESOURCE_LOGO}]]></imageExpression>
            </image>
        </band>
    </detail>
</jasperReport>
ℹ️ This example has been simplified for clarity. A real `.jrxml` contains many additional attributes, layout elements, and Studio-specific property annotations. The elements shown here are the ones VeloxFactory actively reads and acts on. Everything else is interpreted by the render engine as described in Render engine: supported features and expressions.
Pre-Upload Checklist
Before uploading a 
.jrxml to VeloxFactory, verify the following:
The Report Name (
name attribute on 
<jasperReport>) is set, descriptive, and unique.
All resource parameters follow the 
P_RESOURCE_ naming convention and have class 
java.lang.String.
All regular parameters have 
exampleValue and 
required custom properties set where applicable.
All fields have an 
exampleValue custom property set.
The 
<queryString> is empty — the SQL is managed in VeloxFactory.
If the report has a detail band, it contains at least one 
<textField> with a 
$F{...} expression.
Every band has 
splitType="Stretch", including an explicit empty 
<background> band, and the bands follow the JasperReports XSD order (
pageFooter and 
lastPageFooter before 
summary).
The template only uses features listed in Render engine: supported features and expressions (no charts, no crosstabs, no 
$R{...}).
The report previews correctly in Jaspersoft Studio using the local data adapter — this confirms the layout and expressions are valid before upload.
After the upload, render it once in VeloxFactory with realistic data, including enough rows for more than one page. The rendering in VeloxFactory is the reference, not the Studio preview.

Render engine: supported features and expressions
VeloxFactory renders 
.jrxml templates with its own render engine: a pure-PHP implementation of JasperReports, based on the open source project JasperPHP and maintained by us as an independent fork. It needs no Java runtime, but it implements a defined subset of JasperReports rather than the full Java engine. This page lists exactly what that subset is, so you can design templates in Jaspersoft Studio that render the same way in VeloxFactory.
How to set up parameters, fields, resources and the query is described in Creating reports in Jaspersoft Studio. This page covers what happens inside the template: bands, elements, styles, expressions and formatting.
ℹ️ This page describes render engine 1.2. If a template behaves differently from what is described here, the render engine is the reference, not Jaspersoft Studio's preview. Always check a real rendering in VeloxFactory before you release a template.
Two rules for every template
Every band needs 
splitType="Stretch", including an explicit empty 
<background><band splitType="Stretch"/></background>.
Bands must follow the JasperReports XSD order: 
background, 
title, 
pageHeader, 
columnHeader, 
detail, 
columnFooter, 
pageFooter, 
lastPageFooter, 
summary. Jaspersoft Studio refuses to open a file with a different order.
Bands
Band
Behaviour
background
Printed once per page at the top edge, behind the content. Does not push other bands down.
title
Printed once on the first page. 
$F{...} shows the first data row.
pageHeader
Printed on every page. On the first page it follows the title.
columnHeader
Printed on every page that contains detail rows, also after a manual 
<break>.
detail
Printed once per data row. Grows with stretching text fields.
groupHeader / 
groupFooter
Printed whenever the value of the 
groupExpression changes.
columnFooter
Printed below the detail rows of a page.
pageFooter
Printed at the bottom of every page.
lastPageFooter
Replaces the 
pageFooter on the last page. Also works without a 
pageFooter: then a footer appears on the last page only.
summary
Printed once at the end. 
$F{...} shows the last data row, variables hold their final values. If the summary does not fit and moves to a page of its own, that page has no page header, column header or footer, and the 
lastPageFooter appears on the page before. With 
isSummaryWithPageHeaderAndFooter="true" on 
<jasperReport>, the summary page gets page header and footer (the 
lastPageFooter), but still no column header. This is JasperReports behaviour.
noData
Not supported.
Elements
Element
Supported
textField, 
staticText
Horizontal and vertical alignment, rotation, 
markup="html", line spacing (Single, 1_1_2, Double, Proportional), 
textAdjust (StretchHeight, ScaleFont, CutText), 
<box>, 
pattern / 
patternExpression, hyperlinks
rectangle
radius, 
mode, forecolor and backcolor, pen width, colour and style (Solid, Dashed, Dotted), fractional sizes such as 
height="0.8"
line
Pen as for rectangles. Lines thinner than 1 pt are drawn straight.
frame
Background, border, child elements positioned relative to the frame
image
Path or URL as an expression, Base64 data URIs (
data:image/png;base64,...), JPG and PNG. In VeloxFactory, images normally come from 
P_RESOURCE_ parameters.
Barcodes
QR Code, DataMatrix, PDF417, Code 128, Code 39, Code 93, EAN-8, EAN-13, Interleaved 2 of 5, Postnet. The code is an expression.
subreport
Data source from a list field (
$F{items}, also 
new JRBeanCollectionDataSource($F{items})), file name as an expression, 
.jasper is resolved to 
.jrxml
break
Page break, prints page footer, page header and column header
jr:table
Basic tables
Every element respects 
printWhenExpression, evaluated for each row.
Layout rules
StretchHeight makes the band taller, never the elements beside it. The next band starts below the lowest stretched field.
Vertical alignment with StretchHeight: if the text fits into the field, Top, Middle and Bottom apply as usual. Only overflowing text grows downwards from the top.
positionType="Float" moves an element down by the growth of the stretched fields above it. All other elements keep their position.
ScaleFont reduces the font size until the text fits into the box. Line breaks are allowed.
Page breaks fill the page down to the page footer. The decision uses the declared band height.
<box>: 
<pen> applies to all four sides, 
topPen, 
leftPen, 
bottomPen and 
rightPen override it. The colour falls back from the side pen to the box pen, then to 
forecolor, then to black. 
padding sets all four paddings, 
leftPadding etc. override it.
Defaults are the same as in JasperReports:
Rectangle: Opaque, white background, 1 pt black border.
Line: 1 pt. A pen width of 0 draws nothing.
Pen colour: 
lineColor takes precedence over 
forecolor.
Styles
Assignment: 
style="Name" on the 
reportElement. A style with 
isDefault="true" applies to all elements without a style of their own.
Inheritance: 
<style name="Child" style="Parent">.
Precedence: element attribute, then all matching conditional styles in order, then the style, then its parent.
Conditional styles are evaluated again for every row, for example to colour negative quantities red or to shade every second row.
Styles carry: 
mode, 
forecolor, 
backcolor, horizontal and vertical text alignment (
hTextAlign, 
vTextAlign and the older names), 
rotation, 
markup, font name, size, bold, italic, underline, strike-through, 
pattern, 
radius, image scaling and alignment, and the child elements 
<pen>, 
<box> and 
<paragraph>.
⚠️ An element with its own style does not inherit the default style. This is JasperReports behaviour. If a style should build on the default style, set 
style="Default" as its parent.
Expressions
Expressions are written in Java syntax, as in Jaspersoft Studio. They are evaluated by a built-in interpreter; no code is executed on the server. Expressions work in text fields, 
printWhenExpression, conditional styles, variables, 
patternExpression, hyperlinks, images, barcodes and subreport file names.
Syntax
References
$P{name}, 
$F{name}, 
$V{name}
Literals
"text" (with 
\" \\ \n \t \uXXXX), 
'text', 
42, 
1.5, 
10L, 
2.5d, 
true, 
false, 
null
Operators
? :, 
||, 
&&, 
==, 
!=, 
<, 
<=, 
>, 
>=, 
+, 
-, 
*, 
/, 
%, 
!, parentheses
Casts
(String), 
(Integer), 
(Long), 
(Double), 
(BigDecimal), 
(Number), 
(Boolean), 
(Date)
How values behave
+ concatenates as soon as one operand is text, from left to right: 
1 + 2 + "a" gives 
3a, 
"a" + 1 + 2 gives 
a12.
7 / 2 gives 
3 (integer division), 
7 / 2.0 gives 
3.5.
The type comes from the declared 
class of the field, parameter or variable. Declare amounts as 
java.math.BigDecimal, 
java.lang.Double or 
java.lang.Integer; a value declared as 
String is concatenated instead of added.
Three deliberate differences from Java make templates more robust:
null is concatenated as empty text (Java: 
"null").
== compares values like 
.equals().
Arithmetic with 
null returns 
null instead of failing.
Methods
All values
equals, 
toString, 
compareTo
Text
length, 
isEmpty, 
isBlank, 
trim, 
strip, 
toUpperCase, 
toLowerCase, 
substring, 
charAt, 
indexOf, 
lastIndexOf, 
contains, 
startsWith, 
endsWith, 
replace, 
replaceAll, 
replaceFirst, 
matches, 
concat, 
split, 
repeat, 
equalsIgnoreCase
Numbers
intValue, 
longValue, 
doubleValue, 
floatValue, 
setScale(n[, RoundingMode.X]), 
add, 
subtract, 
multiply, 
divide, 
negate, 
abs, 
signum, 
toPlainString
Dates
getTime, 
before, 
after
Lists
size, 
isEmpty, 
get(i), 
contains
Static calls, constants and constructors
Text: 
String.valueOf, 
String.format([Locale,] format, ...), 
String.join
Parsing: 
Integer.parseInt / 
valueOf, 
Long.parseLong, 
Double.parseDouble / 
valueOf, 
BigDecimal.valueOf, 
Boolean.valueOf / 
parseBoolean
Math: 
abs, 
round, 
floor, 
ceil, 
max, 
min, 
pow, 
sqrt
Constants: 
Boolean.TRUE / 
FALSE, 
BigDecimal.ZERO / 
ONE / 
TEN, 
RoundingMode.*, 
Locale.GERMANY, 
GERMAN, 
US, 
UK, 
ENGLISH, 
FRANCE, 
ITALY
Constructors: 
new java.util.Date(), 
new Date(ms), 
new java.text.SimpleDateFormat("...", [Locale]) with 
.format() and 
.parse(), 
new java.text.DecimalFormat("...").format(), 
new BigDecimal("1.5"), 
new Integer(...), 
new String(...), 
new Locale("de", "DE")
Examples
"Customer: " + $P{P_CUSTOMER}
$P{P_NOTE} == null || $P{P_NOTE}.isEmpty() ? "-" : $P{P_NOTE}
$F{status}.equals("late") && $F{qty} > 0
String.format("%s / %05d", $F{order}, $F{pos})
new java.text.SimpleDateFormat("EEEE, d. MMMM yyyy", java.util.Locale.GERMAN).format($F{date})
$F{amount}.setScale(2, java.math.RoundingMode.HALF_UP)
Legacy suffixes
Two JasperPHP shortcuts still work for existing templates: 
$F{amount}.toString() always returns two decimals in German format (
1.234,50), and 
$F{amount}.numberToText() spells out a number (Portuguese). For new templates, use 
pattern instead.
Not supported
$R{...} (resource bundles), arbitrary Java classes, lambdas and field access without a method call (
.length without parentheses). A text field with an unsupported expression falls back to plain placeholder substitution, which usually shows parts of the expression in the output. A condition with an unsupported expression counts as false, so the element is hidden.
Formatting numbers and dates
pattern / 
patternExpression: 
patternExpression takes precedence and is evaluated for each row, for example to switch the number of decimals per article.
Numbers use Java's DecimalFormat: 
#,##0.00, 
0.0%, 
000000, 
#,##0.00 €, 
#,##0.00;(#,##0.00), 
0.00E0. Rounding is HALF_EVEN as in Java; 
setScale rounds HALF_UP by default.
Dates use Java's SimpleDateFormat: 
dd.MM.yyyy, 
EEEE, d. MMMM yyyy, 
HH:mm.
Values that arrive as text are formatted as well when they contain a number or an ISO date (
2026-05-02, 
2026-05-02 14:30:00). This matters because render requests usually pass parameters as text.
Language and locale
Pass the parameter 
REPORT_LOCALE in the render request, for example 
de_DE. It controls decimal and thousands separators, month and day names, 
String.format and 
pattern. Built in are German (including 
de_CH), English, French, Spanish, Italian and Portuguese. Without 
REPORT_LOCALE, the default locale of the installation applies (English unless configured otherwise).
ℹ️ Do not declare 
REPORT_LOCALE as a parameter in the template. It is a built-in JasperReports parameter, and Jaspersoft Studio rejects a second declaration. Pass it in the render request or the schedule only.
Variables
Calculations: Sum, Count, Average, DistinctCount, Highest, Lowest, First, Nothing (current value). Count and Average only count values that are not null.
Reset: 
resetType="Report" or 
"Group". Groups reset correctly even without a group header band.
Expressions can be any supported expression, for example 
$F{qty} * $F{price}.
Built in: 
PAGE_NUMBER and 
REPORT_COUNT. For "Page N of M", use two text fields: 
"Page " + $V{PAGE_NUMBER}, and 
" of " + $V{PAGE_NUMBER} with 
evaluationTime="Report".
Upgrading templates from earlier versions
Templates built for earlier VeloxFactory versions keep working. Check them for these changes:
Conditions in PHP syntax (for example 
is_int(...), 
===, 
and or 
or in 
printWhenExpression) now count as false, and the element is hidden. Rewrite them in Java syntax.
Lines without 
<pen> are 1 pt wide instead of a hairline.
Element attributes override the style (previously the other way round).
Multi-page reports fit more rows per page and repeat the column header on every page.
Workarounds are no longer needed: concatenation with 
+, 
pattern, 
<box> and page footers on every page now work as in Jaspersoft Studio.
Known limits
Charts and crosstabs are not supported and render as an empty area. Use tiles, lists and aggregated groups instead.
noData band and 
$R{...} are not supported.
isBlankWhenNull="false" is ignored; null always prints as empty text.
A band that stretches shortly before the end of a page can reach into the page footer. Leave some space above the footer on pages with long texts.

Managing reports in VeloxFactory
A report in VeloxFactory is more than a file. It is a fully managed configuration - with its own parameters, data fields, image resources, SQL query, data connection, preview images, rendering history, and print records. This page walks through the complete lifecycle of a report configuration, from upload to print.
Screenshot placeholder: 
report-config.index.png
Report Config overview, the landing page after login, with context badges and thumbnails.
The ReportConfig - Central Master Data
The 
ReportConfig is the core entity in VeloxFactory. Every report you manage is a 
ReportConfig record, and everything else in the system either belongs to it or references it. A single 
ReportConfig brings together:
The 
.jrxml template file stored on disk
Its parameters - input values passed at render time
Its fields - data columns that populate the detail band
Its resources - graphic assets (images, logos) embedded in the template
Its SQL query - defined and managed directly in VeloxFactory
Its data connection - the live database to query (optional)
Its context - an organisational label for grouping
Its preview and thumbnail images - generated from example data
Nothing renders without a 
ReportConfig. Nothing prints without one either. It is the starting point for every operation in VeloxFactory.
The Report Configuration Lifecycle
Upload .jrxml
     │
     ▼
Auto-analysis
(parameters, fields, resources detected and created)
     │
     ▼
Complete the configuration
(upload resource files, set example values, write SQL query, assign connection)
     │
     ▼
Generate preview
(renders with example data, stores preview + thumbnail)
     │
     ▼
Ready to render
Each step is described in detail below.
Uploading a Report
When you upload a 
.jrxml file, VeloxFactory immediately analyses it and builds the initial configuration automatically. The following is extracted from the file:
Report name - from the 
name attribute on 
<jasperReport>. Must be unique.
Page dimensions - width and height, converted from Jasper pixels to millimetres.
Detail band presence - whether the report has a repeating data section.
Parameters - all non-resource parameters, including their data types and any 
exampleValue / 
required custom properties set in the 
.jrxml.
Fields - all data fields, including their data types and 
exampleValue custom properties.
Resources - all parameters following the 
P_RESOURCE_ naming convention (image assets).
The result is a fully structured 
ReportConfig record with all its child records in place, but not yet complete. Resource files still need to be uploaded, and the SQL query still needs to be written if a live data connection is used.
⚠️ Report name and file name must be unique. VeloxFactory will reject an upload if a 
ReportConfig with the same report name or the same file name already exists.
The file name may contain letters, digits, dot, hyphen and underscore, must end in 
.jrxml and is limited to 120 characters. Directory parts are not accepted.
Screenshot placeholder: 
report-config.create.png
Report Config create form with the JRXML upload, context and data adapter.
Completing the Configuration
After upload, the report configuration is ready but not yet fully operational. The following steps complete it:
Upload Resource Files
If the report contains image resources (detected as 
P_RESOURCE_ parameters), each one requires an actual file to be uploaded. VeloxFactory cannot render the report until all resource files are in place.
Alternatively, a resource can be linked to a 
CommonReportResource - a shared asset reused across multiple reports, such as a company logo. Linking is permanent: the resource's own file is deleted and the common file is used in its place.
A Common Report Resource serves a second purpose as well: a PNG or JPEG uploaded there can be placed into a mail template as an inline graphic, referenced by its name. The same logo therefore covers the report and the mail it is sent with. See Mail Templates.
Resource files are images: 
png, 
jpg, 
jpeg, 
gif or 
webp. VeloxFactory checks the actual content, not the extension, and refuses a file whose bytes are not one of those formats.
The file name is normalised before it is stored. Any directory part is dropped, inner dots become hyphens (
logo.v2.png is stored as 
logo-v2.png), everything outside letters, digits, hyphen and underscore becomes a hyphen, and the name part is cut at 80 characters. The stored name is what the report refers to, so a renamed file shows up under its normalised name in the resource list.
ℹ️ The linked/uploaded file is the default, not the only option. A single render request can override a resource's image for that call alone via 
resourceOverrides - a local path, a remote URL, or a Base64 upload - without touching this configuration. The file uploaded here is still required as the fallback. See Rendering with our powerful API.
Screenshot placeholder: 
report-config.edit.png
Report Config edit view with parameters, fields and resources.
Review Parameters and Fields
VeloxFactory picks up 
exampleValue and 
required custom properties from the 
.jrxml automatically on upload. If these were not set in Jaspersoft Studio, or if you need to adjust them, you can do so directly in the configuration.
Every parameter and field should have an example value set before generating a preview.
Write the SQL Query and Assign a Connection
If the report fetches live data from a database, assign a 
ReportConnectionConfig and write the SQL query in the Query field. The query is stored in VeloxFactory, not in the 
.jrxml.
Parameters are available as named bindings in the query (
:PARAMETER_NAME). See Creating reports in Jaspersoft Studio for details on how parameter binding works.
A connection is not required if the report has no detail band, or if data will be delivered in the render request itself.
Generating a Preview
Once all resource files are uploaded and all parameters and fields have example values, you can generate a preview. VeloxFactory renders the report using the stored example values, no live data needed, and stores the result as a base64-encoded PDF and a thumbnail image on the 
ReportConfig.
The preview is used in the report list as a visual card and as a quick sanity check that the template renders correctly. It is also what the 
useExampleValues flag triggers during a render request, useful for testing without providing real data.
ℹ️ Preview generation will fail if any resource file is missing or any example value is not set. VeloxFactory checks all three conditions - resources, parameter example values, and field example values - before attempting to render.
Screenshot placeholder: 
report-config.edit.preview.png
Report Config edit view with the generated preview and thumbnail.
Report History Records
Every render request can optionally create a 
ReportHistoryRecord - a full log entry of what was requested and what was returned. This is controlled by the 
createHistoryRecord flag in the render request body and is off by default.
When enabled, the history record captures:
The exact request payload sent to the render endpoint
The full API response
The rendered PDF (Base64-encoded)
A thumbnail of the first page (generated asynchronously in the background)
The rendering status (
ok, 
render_fail, 
error, 
unknown)
The trace ID for cross-referencing with logs
History records are valuable for traceability, you can see exactly what was rendered, when, with what data, and what the result was. From a history record, you can also dispatch a reprint or send the document by mail directly.
ℹ️ Downloads follow the read permission. Downloading a report template, a resource file, a rendered PDF or an xlsx export requires the read permission for that resource. Being signed in is not enough.
When to Skip History Records
History records are entirely optional. There are two good reasons to leave them off:
Performance and storage. Storing the full PDF, request payload, and response for every render adds up. For high-frequency rendering where traceability is not needed, skipping history records keeps the database lean.
Data sensitivity. A history record stores the complete render payload, including all parameters and data passed to the report. If that data is sensitive (personal data, financial figures, medical information), you may not want it persisted on the server at all. Omitting 
createHistoryRecord from the render request ensures nothing is logged.
Retention
History records are automatically purged after a configurable number of days. The retention period is set via the 
PURGE_HISTORY_DAYS environment variable (default: 30 days). Purging runs automatically as a background job, no manual intervention required.
Screenshot placeholder: 
report-history-record.index.filtered.png
Report History Record overview with filters applied and status badges.
Report Mail Tasks
The second way out of VeloxFactory is a mail. A render request can carry a 
mailing segment, and a document that was rendered earlier can be mailed from its history record at any time. Either way a 
ReportMailTask is created, logging recipients, subject, body and attachments, exactly as a print task logs printer and copies.
What a mailing needs is set up once under Configuration: a Mailer holds the SMTP account, a Mail Template holds subject and body with placeholders. The PDF is attached, and on request an xlsx export of the same rows the report was rendered with. Sending is synchronous by default, or handed to the queue.
ℹ️ A mail task blocks its history record from being deleted, just like a print task does. Mail tasks have their own retention setting, 
PURGE_MAILTASKS_DAYS, and are purged before the history records they point at. Full detail on Report Mailing.
Report Print Tasks
A 
ReportPrintTask sends a rendered PDF to a physical printer. Print tasks are created as part of a render request, you render and dispatch to a printer in a single call, by setting 
createPrintTask: true and providing a 
printerName.
Print tasks are always linked to a 
ReportHistoryRecord. This means creating a print task also creates a history record (regardless of whether 
createHistoryRecord is explicitly set), so the printed document is always traceable.
How Printing Works
VeloxFactory does not communicate with printers directly. Instead, it creates a 
ReportPrintTask record and notifies a separate print service - a lightweight C# application running on or near the target machine - which picks up the task and executes the print job.
There are two modes of delivery:
WebSocket (push). If a 
broadcastId is included in the render request, VeloxFactory broadcasts a 
ReportPrintTaskCreated event via WebSocket (Laravel Reverb) the moment the task is created. The print service subscribes to that channel and reacts immediately. This is the recommended mode for real-time printing, the task reaches the printer within milliseconds of the render completing.
Polling (pull). Without a 
broadcastId, no broadcast is sent. The print service must poll the API for new tasks in 
pending status. This works fine for less time-sensitive workflows.
Print Task Status
Status
Meaning
pending
Created, waiting for the print service to pick it up
printed
Print job executed and confirmed by the print service
error
Print service reported a failure
unknown
Status could not be determined
The print service reports status back to VeloxFactory via the API after executing the job. The 
error_message field on the task record contains the failure detail if printing did not succeed.
Copies
The 
numberOfCopies field is passed to the print service as the requested number of printed copies. It defaults to 
1 if not specified. VeloxFactory always renders the PDF exactly once, the print service is responsible for duplicating the output on the printer side.
ℹ️ Print tasks also have configurable retention. They are automatically purged after 
PURGE_PRINTTASKS_DAYS days (default: 30). Like history record purging, this runs in the background without any manual action.
Screenshot placeholder: 
report-print-task.index.png
Report Print Task overview with status badges, printer and the reset action.
Deleting a Report Configuration
A 
ReportConfig can only be deleted when no 
ReportHistoryRecord or 
ReportPrintTask references it. VeloxFactory will reject a deletion request while any such records exist.
When a 
ReportConfig is deleted, the following is removed along with it: the 
.jrxml file from disk, all resource files, and all parameter and field records. The deletion is atomic, if any step fails, the entire operation is rolled back.
⚠️ To delete a ReportConfig that has history records or print tasks, those records must be removed first. Once the retention period has passed and the automatic purge has run, or once the records are manually deleted, the ReportConfig can be removed.

Data adapters for dyn. data control
Reports that display repeating data - lists, tables, card grids - need a data source. VeloxFactory supports two ways to supply that data at render time: a live SQL connection that queries a database automatically, or a dynamic array delivered directly in the render request. Understanding when to use which approach, and how each one works, is key to getting the most out of VeloxFactory.
Two Approaches, One Result
SQL Connection
Dynamic Array
Data source
Live database, queried at render time
JSON array in the render request body
Who fetches the data?
VeloxFactory
The calling application
Connection config needed?
Yes
No
SQL query needed?
Yes
No
Best for
Reports where VeloxFactory has direct DB access
Reports where the caller already has the data
Both approaches produce the same result: a populated report. The choice depends on where your data lives and who is best placed to retrieve it.
Reports without a detail band - purely static layouts driven by parameters - need neither.
ℹ️ The rows are used beyond the PDF. Whatever ends up as field data, fetched by an SQL query or delivered in the request, is also what an xlsx mail attachment is built from, and what the 
[data.first.<column>] placeholders address. For an SQL-driven report that means a mail can be addressed to a recipient the query itself returned. See Report Mailing.
SQL Connections
A 
ReportConnectionConfig defines a live database connection that VeloxFactory uses to fetch data at render time. When assigned to a 
ReportConfig, VeloxFactory executes the configured SQL query against that connection, takes the result rows, and feeds them as field data into the report.
Setting Up a Connection
A connection config holds the credentials and driver settings for one database. Supported drivers are MySQL, MariaDB, PostgreSQL, and Microsoft SQL Server.
Before a connection can be assigned to a report, it must be tested and approved. VeloxFactory runs a test query against the database to verify connectivity, only connections with a passing test are available in the ReportConfig assignment dropdown.
⚠️ The database must be reachable from the VeloxFactory server. For databases in separate networks, use an encrypted VPN tunnel (WireGuard or OpenVPN). Do not expose database ports to the public internet. See Configuration and Data Models for network requirements.
⚠️ MSSQL connections verify the server certificate. Earlier releases accepted any certificate. A connection to a server with a self-signed certificate now fails until either a valid certificate is in place or 
DB_TRUST_SERVER_CERTIFICATE=true is set explicitly in the instance's 
.env. Check your existing connections before you upgrade.
The host of a connection config is checked when it is saved. Loopback and link-local addresses are refused. An instance can narrow this further with 
OUTBOUND_HOST_ALLOWLIST, a comma separated list of the hosts that connections and mailers may point at; an empty list means everything except loopback and link-local. A failed connection test answers with a generic message, the reason is in the application log.
ℹ️ Give the connection a read-only database user. No 
FILE privilege on MySQL and MariaDB, no 
pg_read_server_files on PostgreSQL, 
db_datareader without 
xp_cmdshell on MS SQL Server. The permission 
report-config:update lets a user write the query, which in practice means read access to everything that database user can reach.
Screenshot placeholder: 
report-connection-config.index.png
Report Connection Config overview with driver badges and the approval status.
Writing the SQL Query
The SQL query is written and stored in VeloxFactory, not in the 
.jrxml. It lives on the 
ReportConfig record and is executed against the assigned connection at render time.
The query must return columns whose names match exactly the field names defined in the 
.jrxml. For a report with fields 
articleNumber, 
description, and 
moq, the query must alias its columns accordingly:
SELECT
    art_no          AS articleNumber,
    art_description AS description,
    min_order_qty   AS moq,
    delivery_days   AS deliveryTime,
    supplier_name   AS supplier,
    barcode
FROM articles
ORDER BY art_no ASC
Column names are case-sensitive. 
articleNumber and 
articlenumber are not the same field.
What a Report Query May Contain
A report query is a single read statement. VeloxFactory checks it when the Report Config is saved and refuses anything else:
It must begin with 
SELECT or 
WITH.
It must not contain a semicolon, so a second statement cannot be appended.
It must not use constructs that read files, write files or run commands on the database server: 
INTO OUTFILE, 
INTO DUMPFILE, 
LOAD_FILE, 
LOAD DATA, 
BULK INSERT, 
OPENROWSET, 
OPENDATASOURCE, 
xp_cmdshell, 
sp_OACreate, 
pg_read_file and their relatives.
At most 20,000 characters.
Parameters stay parameters. They are bound by the driver, never pasted into the statement, which is why a value can safely contain quotes or a semicolon.
⚠️ Existing queries keep running, but may no longer save. The check runs when a Report Config is written, not when it renders. A query that predates this release and contains a semicolon, even inside a string literal, is refused the next time the Report Config is edited. Rewrite it with 
CHAR(59) or a parameter.
Using Parameters as SQL Variables
Parameters passed in the render request are available as named bindings in the SQL query using the 
:PARAMETER_NAME syntax. VeloxFactory scans the query for 
:name placeholders before execution and binds only the parameters that are actually referenced, extras are silently ignored.
This makes it straightforward to filter, sort, or paginate the result set based on render-time input:
-- Filter by article number
SELECT
    art_no          AS articleNumber,
    art_description AS description,
    min_order_qty   AS moq
FROM articles
WHERE art_no = :P_ARTICLE_NUMBER
-- Date range filter with two parameters
SELECT
    order_id        AS orderId,
    customer_name   AS customerName,
    order_date      AS orderDate,
    total_amount    AS totalAmount
FROM orders
WHERE order_date BETWEEN :P_DATE_FROM AND :P_DATE_TO
ORDER BY order_date ASC
-- Wildcard search
SELECT
    art_no          AS articleNumber,
    art_description AS description
FROM articles
WHERE art_description LIKE CONCAT('%', :P_SEARCH_TERM, '%')
The render request for the date range example would look like this:
POST /api/v1/report-config/OrderList/render
{
  "outputType": "base64",
  "parameters": {
    "P_DATE_FROM": "2024-01-01",
    "P_DATE_TO":   "2024-03-31"
  },
  "data": [],
  "createHistoryRecord": true,
  "createPrintTask": false
}
Parameter Promotion from Query Results
There is a powerful pattern worth knowing: if a SQL result column has the same name as a registered parameter on the report, VeloxFactory automatically promotes that value from the data rows into the parameters map, before the report renders.
This means you can derive parameter values directly from the database without having to pass them in the render request. The query does the lookup; the result feeds both the detail band and the header parameters in a single call.
Consider a report that prints a picking list for a warehouse order. The header shows the order number, the customer name, and the warehouse location, all parameters. The detail band shows the individual line items, fields. Normally you would have to fetch the order header separately and pass it as parameters. With parameter promotion, a single query can deliver everything:
-- First row drives the header parameters, all rows drive the detail band.
-- P_ORDER_NUMBER, P_CUSTOMER_NAME, and P_WAREHOUSE match registered parameter
-- names and will be promoted automatically. The remaining columns stay as field data.
SELECT
    o.order_number      AS P_ORDER_NUMBER,
    c.customer_name     AS P_CUSTOMER_NAME,
    w.location_code     AS P_WAREHOUSE,
    ol.sku              AS sku,
    ol.description      AS description,
    ol.quantity         AS quantity,
    ol.bin_location     AS binLocation
FROM orders o
JOIN customers c   ON c.id = o.customer_id
JOIN warehouses w  ON w.id = o.warehouse_id
JOIN order_lines ol ON ol.order_id = o.id
WHERE o.order_number = :P_ORDER_NUMBER
ORDER BY ol.bin_location ASC
The render request only needs the order number:
POST /api/v1/report-config/PickingList/render
{
  "outputType": "base64",
  "parameters": {
    "P_ORDER_NUMBER": "ORD-2024-00451"
  },
  "data": [],
  "createHistoryRecord": true,
  "createPrintTask": false
}
VeloxFactory executes the query, detects that 
P_ORDER_NUMBER, 
P_CUSTOMER_NAME, and 
P_WAREHOUSE match registered parameter names, moves their values from the first data row into the parameters map, and renders the report with a populated header and a fully populated detail band, all from one query, one request.
ℹ️ Parameter promotion reads from every row, but only the last encountered value is kept. For consistent results, make sure promoted columns carry the same value across all rows, as in the example above, where the order header data is identical on every line item row.
Dynamic Array
When no 
ReportConnectionConfig is assigned, VeloxFactory expects the data to arrive in the render request itself, as a JSON array in the 
data field. Each object in the array represents one row in the detail band, with keys matching the field names defined in the 
.jrxml.
This approach is ideal when the calling application already has the data in memory, when the data comes from a source VeloxFactory cannot connect to directly, or when the data structure is too dynamic to express in a fixed SQL query.
A complete render request with inline data looks like this:
POST /api/v1/report-config/A5_KanBan/render
{
  "outputType": "base64",
  "parameters": {
    "P_ARTICLE_NUMBER": "4561287-154"
  },
  "data": [
    {
      "articleNumber": "4561287-154",
      "description":   "Packing Carton Size 1 - 200x150x50mm",
      "moq":           250,
      "deliveryTime":  "3 Days",
      "supplier":      "Ninghao Packaging",
      "barcode":       "5698532145712"
    }
  ],
  "createHistoryRecord": false,
  "createPrintTask": false
}
For reports that print one item per page, the 
data array typically contains a single object. For list or table reports, it contains one object per row.
ℹ️ Data types in the array must be compatible with the field types defined in the 
.jrxml. A field declared as 
java.lang.Integer expects a JSON number, not a string. Pass values in their native JSON type, numbers as numbers, booleans as booleans.
Static Reports - No Data Needed
Reports without a detail band require neither a connection config nor a data array. The entire output is driven by parameters alone. Common examples: cover pages, certificates, summary headers, QR code labels, or any document where the layout is fixed and all variable content comes from a handful of input values.
For these reports, the render request simply omits 
data entirely:
POST /api/v1/report-config/CertificateOfConformity/render
{
  "outputType": "url",
  "parameters": {
    "P_PRODUCT_NAME":   "Industrial Bearing 6205-2RS",
    "P_BATCH_NUMBER":   "BAT-2024-0077",
    "P_ISSUE_DATE":     "2024-03-15",
    "P_INSPECTOR_NAME": "M. Fischer"
  },
  "createHistoryRecord": true,
  "createPrintTask": false
}

Rendering reports in VeloxFactory
Turning a Report Config into a document: from the frontend, from the API, and what every render leaves behind.

Rendering from the frontend
Every report configuration in VeloxFactory has a built-in Generate PDF page: a small workstation for one report template that renders it directly from the browser, without writing a single line of code or touching the API. It is the fastest way to produce a PDF, test a configuration, or trigger a print job on demand.
The page follows one principle: settings once, then only the data. How the output should be produced, preview or print, which printer, how many copies, whether a history record is kept, is decided once per report and then stays out of the way. From there, every render is nothing but filling in the values that actually change and pressing one button.
Screenshot placeholder: 
generate-pdf.page.png
Generate PDF page with the header row (report name, settings summary, Output Settings button), parameter table and the action row.
Opening the Generate PDF Page
There are two ways to reach the page. In the report configuration overview, each row has an action menu that contains Generate PDF, taking you straight to the render page. Alternatively, open a report configuration and use Generate PDF from within the report view.
The header row shows the report name and, as a compact summary line, the active data adapter and the stored output settings: mode, printer, copies, broadcast ID and whether a history record is created. The data adapter is either the assigned 
ReportConnectionConfig (including driver and database) or dyn. Array when no SQL connection is configured, and it decides which input sections appear further down.
Screenshot placeholder: 
report-config.index.action-menu.png
Report configuration overview, opened action menu with Generate PDF and Download.
Output Settings
The first time you open the page for a report, the Output Settings dialog opens by itself, because VeloxFactory does not yet know what you want to do with the result. Afterwards it only opens when you click the Output Settings button in the header.
  
    
      
Setting
      
Default
      
Description
    
  
  
    
      
Mode
      
Preview and download only
      
Decides what happens with the rendered PDF, see the table below.
    
    
      
Printer
      
-
      
Printer picker over the active printer master data, free text is allowed as well. Required in both printing modes.
    
    
      
Copies
      
1
      
Copies passed to the print service, between 1 and 100. Does not trigger multiple renders.
    
    
      
Broadcast ID
      
-
      
WebSocket channel of the print service. Filled in automatically when the chosen printer has one stored.
    
    
      
Create History Record
      
On
      
Saves request, response, PDF and thumbnail of every render to the report history.
    
    
      
Send results via Mail
      
Off
      
Mails every render of this report, see Mailing the result below.
    
  
The three modes:
  
    
      
Mode
      
Preview
      
Print task
    
  
  
    
      
Preview and download only
      
yes
      
no
    
    
      
Print only, no preview
      
no
      
yes
    
    
      
Preview and print
      
yes
      
yes
    
  
In Preview and download only the printer and broadcast fields are hidden, there is nothing to print to. In the two printing modes a printer is mandatory: saving without one fails and the dialog reopens with everything you entered still in place.
Settings are kept per report configuration in your session. Two report templates therefore keep independent settings, they survive leaving the page and coming back, and they end when your session does. Clear settings at the bottom of the dialog removes them, the dialog then opens by itself on the next visit.
ℹ️ The settings are yours, not the report's. They live in your session, so a colleague configuring the same report for a different printer never affects your workstation.
Screenshot placeholder: 
generate-pdf.settings-modal.png
Output Settings dialog with mode dropdown, printer picker, copies, broadcast ID, history toggle, the mailing block and the Clear settings button.
Mailing the Result
Send results via Mail turns every render of this report into a mail as well. While the switch is on, the dialog shows the mailing fields:
Field
Description
Mailer / Mail Template
The SMTP account and the template the mail is built from. Only active records are offered.
To, CC, BCC
Comma separated address lists. Placeholders are allowed, an address containing one is checked after the render, not in the dialog.
Contact Name
Free text for a personal greeting, available in the template as 
[contactName].
Attach PDF Report
On by default, with an optional name the attachment carries in the mail.
Attach Excel Report
Attaches an xlsx built from the rendered rows, with an optional attachment name and a switch for the parameter block above the table.
Send in background
Hands the mail to the queue instead of waiting for the SMTP server.
The values stay in the form even while the switch is off, so turning mailing off for one render loses nothing. After the render the notification says what happened to the mail: sent, queued, or a warning with the reason. A mail that fails never turns a successful render into an error.
ℹ️ The mailing block only appears when you can use it. It needs the permission to create mail tasks plus at least one active mailer and one active mail template. The same block sits in the Scan2Print configuration and on a render job in the Job Scheduler. Details on Report Mailing.
Report Parameters
If the report defines parameters, a parameter input table is shown. Each parameter gets its own typed input field, derived automatically from the Java class declared in the 
.jrxml:
A 
java.lang.String parameter becomes a text field.
A 
java.sql.Date parameter becomes a date picker.
A 
java.lang.Integer parameter becomes a number input with integer constraints.
A 
java.lang.Boolean parameter becomes a toggle switch.
And so on for all supported types.
Parameters marked as required in the report configuration must be filled in before the form can be submitted. Optional parameters can be left empty, VeloxFactory silently drops empty parameter values and does not include them in the render request.
Report Lines - Manual Data Entry
The Report Lines section only appears when the report has no SQL connection assigned, i.e. when the data adapter is 
dyn. Array. In this case, VeloxFactory has no database to query, so the detail band data must be entered manually in the browser.
The section shows a table with one column per field defined in the report. Each cell contains a typed input matching the field's data type. You fill in one row of values per data record you want to appear in the report.
To add more rows, use the Add Row button, it clones the input row and appends a new empty one. Individual rows (except the first) can be removed with the delete button on the right. Empty fields are not transferred to the render request.
ℹ️ When a SQL connection is assigned, the Report Lines section is hidden. VeloxFactory fetches the data automatically from the database using the configured query, no manual input needed.
Less typing: prefill, example values, clear
Three small helpers remove most of the repetitive work when the same report is rendered again and again:
Prefill from the last run. Parameters and report lines come back filled with the values of your previous render in this session. The values are stored on every submit, successful or not, so a failed render can be corrected instead of retyped.
Fill example values. Fills every parameter and the first line row with the example values stored in the report configuration. This is the frontend counterpart of the API's 
useExampleValues, useful for a quick smoke test of a new template.
Clear inputs. Empties all parameters and removes every line row except the first one.
Resources
If the report has image resources, a collapsible Resources section is available on the page. It shows a preview thumbnail of each resource file, its parameter name, and its file name. Resources are handled automatically at render time, you do not interact with them during rendering. The section is informational only, confirming which image files are currently assigned.
Generating
Once the values are in place, click Generate. There is no confirmation dialog: the stored output settings already say what is supposed to happen with the result. The request is processed synchronously, the page waits for the result and displays it immediately.
The Result
Success
In the two modes with a preview, the page shows a green confirmation banner, a Download PDF button and the generated PDF as an inline preview, sized to the report's actual page dimensions. If a history record was created, the download button serves the stored file, otherwise the PDF is offered straight from the response.
In Print only, no preview is rendered at all. The banner then reads Sent to <printer> (<n>x), which is the whole point of that mode: a station that prints and moves on.
If a history record was created, a View History button links to the new 
ReportHistoryRecord. If a print task was dispatched, a View Print Task button links to the 
ReportPrintTask where you can follow its status.
⚠️ Reloading the page renders the report again. The result lives in the response, so a browser reload repeats the render, including a new print task if the mode creates one.
Screenshot placeholder: 
generate-pdf.result.png
Generate PDF page after a render, with the result block and the inline PDF.
Errors
If the render fails, the page shows a red error banner listing all error messages returned by VeloxFactory, and everything you entered stays on screen. Common causes are missing required parameters, a SQL query that returns no rows, or a resource file that was removed after the configuration was last saved.
If a history record was created before the error occurred, the failed attempt is recorded including the error details, which is useful for diagnosing what went wrong.

Rendering with our powerful API
Everything the Generate PDF page does in the browser, the API does programmatically, with more control, lower overhead, and the same rendering engine underneath. A single 
POST request renders a report, optionally logs the result, and optionally dispatches a print job, all in one call.
Screenshot placeholder: 
api-docs.png
The interactive API reference at /docs, generated by Scribe.
The Render Endpoint
POST /api/v1/report-config/{id}/render
The 
{id} segment accepts either the numeric ID of the 
ReportConfig or its report name, the name set in Jaspersoft Studio and stored in VeloxFactory. Both of these are equivalent:
POST /api/v1/report-config/1/render
POST /api/v1/report-config/A5_KanBan/render
Using the report name is convenient for integrations: it stays stable even if the database record is recreated, and it makes the request self-documenting.
Request Body
  
    
      
Field
      
Type
      
Required
      
Description
    
  
  
    
outputType
string
✓
Output format: 
base64, 
url, or 
none. See below.
    
parameters
object
Key-value map of parameter names to values. Required parameters must be present or the request is rejected.
    
resourceOverrides
object
Per-render override for 
P_RESOURCE_* image parameters, keyed by parameter name. See Dynamic Resource Overrides below.
    
data
array
Array of field objects, one per detail band row. Each object's keys must match the report's field names. Only needed when no SQL connection is configured. Can include per-row images, see Per-Row Images via Data Fields below.
    
createHistoryRecord
boolean
✓
Whether to create a 
ReportHistoryRecord for this render. Stores the full request, response, and rendered PDF.
    
createPrintTask
boolean
✓
Whether to dispatch the rendered PDF to the print service.
    
printerName
string
if print task
Target printer name. Required when 
createPrintTask is 
true.
    
numberOfCopies
integer
Number of copies passed to the print service. Defaults to 
1. VeloxFactory always renders once, the print service handles duplication.
    
broadcastId
string
WebSocket channel ID. If provided, VeloxFactory broadcasts a 
ReportPrintTaskCreated event when the print task is created. Omit to rely on polling.
    
useExampleValues
boolean
Use the stored example values instead of supplying 
parameters and 
data. Useful for testing. API-only - not available in the frontend. See below.
    
laconicResponse
boolean
Return only the essential output fields instead of the full response. Reduces payload size significantly for high-frequency rendering. See below.
    
traceId
string
Custom trace identifier for this request. Auto-generated (UUID) if not provided. Must be unique across all history records if supplied.
    
mailing
object
Send the rendering by mail after a successful render. See Mailing the rendering below.
  
Dynamic Resource Overrides
Every 
P_RESOURCE_* image parameter (a logo, a product photo, a line-art reference) normally resolves to whichever file is uploaded or linked on the 
ReportConfig itself. 
resourceOverrides lets a single render request swap that image out, without touching the report configuration, useful for per-customer branding, per-item product photos, or any other case where the image genuinely varies from call to call.
POST /api/v1/report-config/A4_AssemblyBOM/render
{
  "outputType": "base64",
  "parameters": { "P_PROJECT_NUMBER": "PRJ-2026-0417" },
  "resourceOverrides": {
    "P_RESOURCE_ASSEMBLY_IMAGE": { "path": "https://cdn.example.com/parts/4471.png" }
  },
  "createHistoryRecord": false,
  "createPrintTask": false
}
resourceOverrides is an object keyed by resource parameter name. Each entry supports exactly one of two modes:
  
    
      
Key
      
Type
      
Description
    
  
  
    
path
string
A path to a readable file inside the resources folder of the instance, or an 
https:// URL. Remote URLs are fetched directly by the render engine at render time. A path that leaves the resources folder and any scheme other than 
https are refused.
    
base64
string
Base64-encoded image bytes. VeloxFactory decodes them, writes a temporary file for the duration of the render, and deletes it immediately afterward.
    
fileName
string
Optional, used only alongside 
base64 to infer the file extension.
  
Base64 example:
{
  "outputType": "base64",
  "resourceOverrides": {
    "P_RESOURCE_ASSEMBLY_IMAGE": {
      "base64": "iVBORw0KGgoAAAANSUhEUgAA...",
      "fileName": "part-4471.png"
    }
  },
  "createHistoryRecord": false,
  "createPrintTask": false
}
⚠️ A resource must still be linked or uploaded on the 
ReportConfig before it can be overridden. 
resourceOverrides replaces the resolved path for a single render, it does not exempt a 
P_RESOURCE_* parameter from needing a default resource in place. Rendering still fails with the usual 
"Not all resources for this report have been uploaded yet!" error if no file or 
CommonReportResource is linked at all.
ℹ️ Do not set the same parameter in both 
parameters and 
resourceOverrides. VeloxFactory rejects the request with a 
422 if a key appears in both, to avoid ambiguous precedence.
{
  "success": false,
  "errors": ["Parameter 'P_RESOURCE_LOGO' is set in both 'parameters' and 'resourceOverrides' - use only one."],
  "status": 422
}
Other validation errors follow the same pattern: an unknown resource parameter name, a 
path that leaves the resources folder or cannot be read, a URL that is not 
https://, or invalid 
base64 all return a descriptive 
422 rather than failing deep inside the render engine.
Per-Row Images via Data Fields
resourceOverrides covers one image per report-level 
P_RESOURCE_* parameter, the same picture used across the whole render. Some reports need the opposite: a different image for every row of the detail band, for example a product photo per line item in a parts list or an order. That case does not need 
resourceOverrides at all, it works through the 
data array directly.
An 
<image> element in a 
.jrxml is not limited to 
$P{...} parameter expressions, it accepts a field expression just like any text field:
<image>
    <reportElement x="0" y="24" width="120" height="100" uuid="..."/>
    <imageExpression><![CDATA[$F{partPhoto}]]></imageExpression>
</image>
With that in place, every object in the render request's 
data array can carry its own 
partPhoto value, resolved independently per row, using the same three delivery styles as 
resourceOverrides:
POST /api/v1/report-config/PartsList/render
{
  "outputType": "base64",
  "data": [
    { "partNumber": "4471-A", "partPhoto": "https://cdn.example.com/parts/4471.jpg" },
    { "partNumber": "4471-B", "partPhoto": "/var/www/resources/parts/4471b.png" },
    { "partNumber": "4471-C", "partPhoto": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." }
  ],
  "createHistoryRecord": false,
  "createPrintTask": false
}
  
    
      
Field value
      
Behaviour
    
  
  
    
Local path
Read directly from the filesystem by the render engine.
    
http(s):// URL
Fetched directly by the render engine at render time, one request per row.
    
data:image/png;base64,...
Decoded inline, no temporary file involved.
    
data:image/jpg;base64,...
Same as PNG. Note the MIME token must be exactly 
image/jpg.
  
⚠️ 
data:image/jpeg;base64,... is not recognized. The render engine only matches the literal prefixes 
data:image/png;base64, and 
data:image/jpg;base64, - the far more common 
image/jpeg MIME token is not one of them and the image silently fails to render. Always encode JPEG uploads with the 
image/jpg token in the data URI, regardless of what the source tool actually calls the file.
ℹ️ No request-level syntax needed. Unlike 
resourceOverrides, per-row images are just regular field values, there is no validation, no linked-resource requirement, no restriction on the location, and no separate object in the request body. Whatever the field resolves to at render time is handed straight to the render engine.
Output Types
The 
outputType field controls how, or whether, the rendered PDF is returned.
base64: The PDF is Base64-encoded and returned inline in 
output.reportPdfBase64. No file is written to disk. This is the most common choice for integrations that process the PDF immediately.
url: The PDF is saved to the VeloxFactory history storage and a URL pointing to that file is returned in 
output.reportUrl. Useful when the calling application needs to hand off a link rather than handle raw bytes.
none: No PDF data is returned at all. Valid only when 
createPrintTask is 
true, the PDF is rendered internally and handed to the print service without being exposed in the response. Use this when the response payload is irrelevant and you only care about getting the document to the printer.
⚠️ 
outputType: none requires 
createPrintTask: true. Requesting output type 
none without a print task is rejected with a validation error, there would be nothing to do with the rendered PDF. A 
mailing segment does not replace the print task here, and a mail on a render that produced no PDF goes out without its attachment.
useExampleValues - API-only Testing Mode
When 
useExampleValues: true is set, VeloxFactory ignores any 
parameters and 
data in the request body and instead uses the example values stored on the 
ReportConfig. This is the same data used to generate the report preview in the frontend.
It is a convenient way to verify that a report renders correctly after configuration changes, no test data needs to be assembled:
POST /api/v1/report-config/A5_KanBan/render
{
  "outputType": "base64",
  "useExampleValues": true,
  "createHistoryRecord": false,
  "createPrintTask": false
}
ℹ️ 
useExampleValues is an API-only feature. The Generate PDF page in the browser always requires parameters and data to be entered manually. For frontend testing, use the example values from the report configuration edit page.
laconicResponse - Minimal Output
By default, a successful render response includes the full 
ReportConfig record, the input parameters and data echoed back, and any linked 
ReportHistoryRecord and 
ReportPrintTask. For many production integrations, this detail is unnecessary, the caller only needs the PDF.
Setting 
laconicResponse: true strips the response down to the essentials: just the 
traceId and the 
output block. Everything else (
input, 
reportConfig, 
reportHistoryRecord, 
reportPrintTask) is omitted.
The two response shapes are shown in detail in the Response Structure section below.
ℹ️ The laconic mode also suppresses 
reportMeta in error responses. If a render fails in laconic mode, the error response contains only the error messages, the field and parameter metadata is not included.
A Complete Request
Here is a full render request for a KanBan label, dynamic array data, a parameter, history logging enabled, print task dispatched via WebSocket:
POST /api/v1/report-config/A5_KanBan/render
{
  "outputType": "base64",
  "parameters": {
    "P_ARTICLE_NUMBER": "4561287-154"
  },
  "data": [
    {
      "articleNumber": "4561287-154",
      "description":   "Packing Carton Size 1 - 200x150x50mm",
      "moq":           250,
      "deliveryTime":  "3 Days",
      "supplier":      "Ninghao Packaging",
      "barcode":       "5698532145712"
    }
  ],
  "createHistoryRecord": true,
  "createPrintTask": true,
  "printerName": "WarehousePrinter01",
  "numberOfCopies": 1,
  "broadcastId": "Standard",
  "laconicResponse": false
}
Response Structure
Full Response
The full response (default, 
laconicResponse: false or omitted) includes the rendered output, the echoed input, the full 
ReportConfig snapshot, and any created 
ReportHistoryRecord and 
ReportPrintTask:
{
  "success": true,
  "count": 1,
  "data": {
    "model": "ReportRendering",
    "traceId": "ec1e29de-7aca-4c59-9722-ae9edc7d24d7",
    "input": {
      "parameters": { "P_ARTICLE_NUMBER": "4561287-154" },
      "data": [
        {
          "articleNumber": "4561287-154",
          "description":   "Packing Carton Size 1 - 200x150x50mm",
          "moq":           250,
          "deliveryTime":  "3 Days",
          "supplier":      "Ninghao Packaging",
          "barcode":       "5698532145712"
        }
      ]
    },
    "output": {
      "reportPdfFileName": "a7dd0ea5-85fd-481c-998b-fa9819c2e84c.pdf",
      "reportPdfBase64":   "JVBERi0xLjQ..."
    },
    "reportConfig": {
      "model": "ReportConfig",
      "id": 1,
      "name": "A5_KanBan",
      ...
    },
    "reportHistoryRecord": {
      "model": "ReportHistoryRecord",
      "id": 4,
      "traceId": "ec1e29de-7aca-4c59-9722-ae9edc7d24d7",
      "outputType": "Base64",
      "status": "Ok"
    },
    "reportPrintTask": {
      "model": "ReportPrintTask",
      "id": 4,
      "traceId": "ec1e29de-7aca-4c59-9722-ae9edc7d24d7",
      "broadcastId": "Standard",
      "printerName": "WarehousePrinter01",
      "numberOfCopies": 1,
      "status": "Pending",
      "errorMessage": null
    }
  },
  "links": { "first": null, "last": null, "prev": null, "next": null },
  "meta": {
    "traceId": "ec1e29de-7aca-4c59-9722-ae9edc7d24d7",
    "pagination": {
      "currentPage": 1,
      "lastPage": 1,
      "perPage": 1,
      "total": 1,
      "from": 1,
      "to": 1,
      "hasMorePages": false,
      "path": "https://your-instance/api/v1/report-config/A5_KanBan/render"
    }
  },
  "status": 200
}
Laconic Response
With 
laconicResponse: true, the response contains only what is needed to retrieve the PDF:
{
  "success": true,
  "count": 1,
  "data": {
    "model": "ReportRendering",
    "traceId": "555d073b-a630-4096-acd1-643b85ed5cc9",
    "output": {
      "reportPdfFileName": "8de016b5-4cf9-423a-9575-8c3155e35410.pdf",
      "reportPdfBase64":   "JVBERi0xLjQ..."
    }
  },
  "links": { "first": null, "last": null, "prev": null, "next": null },
  "meta": {
    "traceId": "555d073b-a630-4096-acd1-643b85ed5cc9",
    "pagination": {
      "currentPage": 1,
      "lastPage": 1,
      "perPage": 1,
      "total": 1,
      "from": 1,
      "to": 1,
      "hasMorePages": false,
      "path": "https://your-instance/api/v1/report-config/A5_KanBan/render"
    }
  },
  "status": 200
}
The 
traceId is always included, it links this render to any created history record or print task, making it useful for cross-referencing even in laconic mode.
The envelope around 
data is the one every endpoint uses: a render reports a single page in 
meta.pagination and carries no page links. See Response Structure on Meet the API.
Mailing the Rendering
A render request can carry an optional 
mailing segment. Once the render succeeded, VeloxFactory sends an HTML mail through a configured mailer, using a configured mail template, with the PDF attached and, on request, an xlsx export of the same data.
POST /api/v1/report-config/DeliveryNote/render
{
  "outputType": "base64",
  "parameters": { "P_ORDER_NO": "4711" },
  "createHistoryRecord": true,
  "createPrintTask": false,
  "mailing": {
    "mailer": "Office SMTP",
    "mailTemplate": "Report Delivery",
    "to": ["[data.first.customerEmail]"],
    "contactName": "[data.first.customerName]",
    "includePdf": true,
    "pdfFileName": "Order_[parameters.P_ORDER_NO]",
    "includeExcel": true,
    "includeParameters": true,
    "sendAsync": false
  }
}
mailer and 
mailTemplate take the ID or the unique name of the master data record. Recipients, contact name and attachment names accept the same placeholders as the mail template, which is what makes the segment useful for reports fed by an SQL adapter: 
[data.first.<column>] addresses the rows the query actually fetched, so the recipient is a result of the render rather than an input to it.
The created mail task is returned in 
reportMailTask, next to 
reportPrintTask.
ℹ️ A failed mailing never fails the render. Whatever goes wrong with the mail, the render response stays a success and the detail lands in 
meta.mailing. The one combination refused up front is 
outputType: "preview" together with 
mailing, a preview render deletes its own file immediately and has nothing to attach.
The full reference, including every field, the placeholder rules, the rate limits and how to mail a rendering that already exists, is on Report Mailing.
Running It on a Schedule
Everything on this page describes a request somebody makes. The same body can be handed to the Job Scheduler instead, which then makes the request itself, on a crontab expression, as the user who created the schedule and with one of that user's API tokens.
The payload of a render job is this body verbatim, with two differences: 
traceId is left out, because every run generates its own, and 
outputType is limited to 
base64, 
url and 
none. Parameters and data rows additionally accept placeholders such as 
[now.date] or 
[uuid], resolved at the start of each run.
ℹ️ See Render Jobs for the schedule around it, and The Job Scheduler for how runs are fired and logged.
Errors
Validation Errors - HTTP 422
Missing required fields, an invalid 
outputType value, or a missing 
printerName when a print task is requested all produce a 
422 response with an 
errors array describing the violations.
Required parameters that are not present in the request also return a 
422, one error message per missing parameter:
{
  "success": false,
  "errors": [
    "Parameter P_DATE_FROM is required.",
    "Parameter P_DATE_TO is required."
  ],
  "meta": { "traceId": "..." },
  "status": 422
}
Render Errors - HTTP 400
If the request passes validation but the renderer itself fails, for example an empty data array for a report with a detail band, an SQL query that returns no rows, a type mismatch between field values and declared Java types, or a broken SQL query, the response comes back with HTTP 
400 and a 
success: false payload.
In full (non-laconic) mode, a 
reportMeta block is included in the 
meta object alongside the 
traceId. This snapshot lists the report's fields, parameters, and resources at the time of the failure, useful for diagnosing mismatches between the request payload and what the report actually expects:
{
  "success": false,
  "errors": [
    "No data delivered (or fetched via SQL using parameters) while data deliverance is mandatory for reports with detail bands or SQL queries."
  ],
  "meta": {
    "traceId": "08deac82-274d-4f56-b9d0-d9fdb6280f8f",
    "reportMeta": {
      "resourceList": [
        { "parameterName": "P_RESOURCE_LOGO", "fileName": "Logo_Dark.png" }
      ],
      "parameterList": [
        { "parameterName": "P_ARTICLE_NUMBER", "dataType": "java.lang.String" }
      ],
      "fieldList": [
        { "fieldName": "articleNumber", "dataType": "java.lang.String" },
        { "fieldName": "description",   "dataType": "java.lang.String" },
        { "fieldName": "moq",           "dataType": "java.lang.Integer" },
        { "fieldName": "deliveryTime",  "dataType": "java.lang.String" },
        { "fieldName": "supplier",      "dataType": "java.lang.String" },
        { "fieldName": "barcode",       "dataType": "java.lang.String" }
      ]
    }
  },
  "status": 400
}
If a 
ReportHistoryRecord was requested (
createHistoryRecord: true), it is still created even when the render fails, the error is recorded in the history entry, which makes it possible to review failed renders from the frontend alongside successful ones.

The concept of Report History Records
Every render request tells VeloxFactory what to produce. A 
ReportHistoryRecord remembers exactly what was asked for, what came back, and what the result looked like, permanently, until you decide otherwise. It is the foundation for traceability, debugging, and on-demand reprinting in VeloxFactory.
Screenshot placeholder: 
report-history-record.index.filtered.png
Report History Record overview with filters applied and status badges.
What Gets Stored
A 
ReportHistoryRecord is created at render time when 
createHistoryRecord: true is set in the request, or automatically when a print task is dispatched. It captures a complete snapshot of the rendering event:
Field
Description
traceId
Unique identifier shared across the render request, the history record, and any linked print task. Used to correlate events in logs and across systems.
reportConfig
Reference to the 
ReportConfig that was rendered.
outputType
The output type used: 
base64, 
url, or 
none.
apiPayload
The complete render request body: parameters, data, flags, everything sent to the render endpoint. Stored as JSON.
apiResponse
The complete API response returned by VeloxFactory, including any errors and, unless the render was laconic, the input it actually worked with. Stored as JSON.
reportPdf
The rendered PDF, Base64-encoded. Present on successful renders; 
null on failure.
reportPdfFileName
The UUID-based filename assigned to the rendered PDF.
reportExcelFileName
Filename of the xlsx export, present when a mailing asked for one. The file hangs on the record, is downloadable from it and is deleted with it.
reportThumbnail
A thumbnail image of the first page of the rendered PDF. Generated asynchronously in the background after the record is created.
status
Automatically calculated from the stored response. See below.
reportPrintTasks
Every print job dispatched from this record, with printer, copies and status. A record can hold any number of them.
reportMailTasks
Every mail sent from this record, with recipients, subject, the rendered body and the attachment names.
audit
Who created the record and when, who last updated it, and which API token was used in either case. VeloxFactory derives 
creationMethod and 
updateMethod from it, 
Frontend or 
API, depending on whether a token was present on the request.
The audit block is what turns a history record into an answer to "who printed this". A render triggered by an integration carries the token it was made with, a render triggered in the browser carries the user.
How It Comes Back from the API
The record is stored in full, but a response only carries what you ask for. Four query parameters control this, and they matter, a history record with an embedded PDF is a large object:
Parameter
Default
Effect
withApiPayloads
true
Includes 
apiPayloadBase64 and 
apiResponseBase64. Both are Base64-encoded, so the stored JSON survives transport unchanged.
withMedia
false
Adds the 
media block with 
reportPdfBase64, 
reportPdfFileName and 
thumbnailBase64.
withRelations
false
Adds the full 
reportConfig, plus 
reportPrintTasks and 
reportMailTasks.
withAudit
false
Adds the 
audit block described above.
Without any of them a record comes back as a compact summary: ID, trace ID, output type, status and the payloads. That is the right shape for a list view, and it is what the frontend's history overview uses.
Status
The status of a 
ReportHistoryRecord is calculated automatically every time the record is saved, based on the content of the stored API response:
Status
Meaning
Ok
No errors in the response and a PDF was produced. The render completed successfully.
Error
The response contains one or more errors. The render failed, the error messages are stored in the API response payload.
Render Fail
No errors in the response, but no PDF was produced either. An edge case indicating something unexpected occurred during rendering.
Unknown
Status could not be determined from the stored response.
History records are created for both successful and failed renders. A failed render still produces a complete record, including the error messages, which is often more useful than a successful one when something goes wrong.
The Thumbnail
When a history record is created, VeloxFactory dispatches a background job that converts the first page of the rendered PDF into a thumbnail image using 
pdftoppm (part of 
poppler-utils). The thumbnail is stored on the record and displayed in the history list and the report card grid, giving you an immediate visual of what was produced without opening the PDF.
ℹ️ Thumbnail generation runs asynchronously. The history record is available immediately after rendering; the thumbnail appears once the background job has completed. This requires the Laravel queue worker (Supervisor) to be running. If the queue is down, thumbnails will not be generated until it is back up.
Traceability and Debugging
The most valuable aspect of a history record is not the PDF, it is the payload. Every record stores the exact request that triggered the render and the exact response that came back. This means you can answer the following questions at any point in the future, without touching the calling application:
What parameters were passed to this render?
What data was submitted, and which rows the report was actually filled with?
Was the render triggered via the frontend or the API?
What did VeloxFactory return, and did it succeed?
If it failed, what was the exact error message?
The 
traceId ties everything together. It is present on the history record, on any linked print task, and in the server logs. When something goes wrong in production and you have a 
traceId, you can pull the history record and reconstruct the entire event in seconds.
Screenshot placeholder: 
report-history-record.show.png
Report History Record detail page with status, payload, PDF preview and the actions.
Reprinting from a History Record
A successful history record holds the rendered PDF. That PDF can be dispatched to a printer at any time, without re-rendering the report, using the dedicated print endpoint:
POST /api/v1/report-history-record/{id}/print
{
  "printerName": "WarehousePrinter01",
  "numberOfCopies": 1
}
VeloxFactory creates a new 
ReportPrintTask from the stored PDF, assigns it a derived trace ID (the original trace ID with a short random suffix), and dispatches it to the print service. The original history record is linked to the new print task.
This is useful in several scenarios: a print job failed and needs to be retried, a physical document was lost and needs to be reprinted, or a record needs to be dispatched to a different printer than the one originally used.
ℹ️ Reprinting uses the stored PDF, it does not re-render the report. The document produced is identical to the original. If the report template or its data has changed since the original render, those changes are not reflected in the reprint.
This endpoint is also available directly from the frontend, the history record detail view has a Print button that opens a modal to enter the printer name and number of copies.
Screenshot placeholder: 
report-history-record.print.modal.png
Print dialog of a Report History Record with the printer picker and the copies field.
Mailing from a History Record
The same idea applies to mail. A stored rendering can be sent to anyone at any time, without re-rendering:
POST /api/v1/report-history-record/{id}/mail
{
  "mailer": "Office SMTP",
  "mailTemplate": "Report Delivery",
  "to": ["disposition@example.com"],
  "includePdf": true,
  "includeExcel": false,
  "sendAsync": false
}
VeloxFactory creates a new 
ReportMailTask from the stored PDF, gives it a derived trace ID, and sends the mail through the chosen mailer. Recipients, contact name and attachment names accept the same placeholders as a mailing in the render request, resolved against the parameters and rows stored on the record.
If 
includeExcel is set and the record does not have an xlsx yet, VeloxFactory builds one on the fly and attaches it to the record. The export uses the rows the report was actually filled with, which includes the rows an SQL adapter fetched at render time: they travel back in the render response and are stored on the record, so a report that gets its data from a live connection exports just as well as one whose rows came in the request.
⚠️ One case has nothing to export. A render made with 
laconicResponse: true stores a response without its input segment. If that request carried no 
data of its own either, the record holds no rows, and a later export answers with a clear error instead of an empty sheet. Render with the mailing segment, or without 
laconicResponse, when an xlsx may be wanted afterwards.
In the frontend the detail view has a Mail button next to Print, opening a dialog with mailer, template, recipients, attachments and the background switch. Every mail sent from this record is listed on the record itself, and in the Mail Queue.
Screenshot placeholder: 
mailing.history-record-modal.png
Mail dialog of a Report History Record with mailer, template, recipients, attachments and the background switch.
ℹ️ Mailing uses the stored PDF too. The document that arrives is identical to the original rendering. The full reference is on Report Mailing.
Retention and Deletion
Automatic Purging
History records are cleaned up by the Purge Job, the consolidated cleanup schedule of the Job Scheduler. How long a record is kept is a retention on that schedule, editable in the frontend or through the API; an empty value switches the step off entirely. The 
PURGE_HISTORY_DAYS environment variable supplies the value the schedule is created with, nothing more.
Deletion Constraints
A 
ReportHistoryRecord cannot be deleted while any 
ReportPrintTask or 
ReportMailTask still references it. The linked tasks must be removed first. VeloxFactory provides a dedicated endpoint for the print tasks:
DELETE /api/v1/report-history-record/{id}/delete-all-report-print-tasks
This removes all print tasks associated with the record in one call. Mail tasks have their own retention on the Purge Job, which runs before the history records for exactly this reason, and they can be deleted individually from the Mail Queue. Once no task references the record any more, the history record itself can be deleted, which also removes its PDF and its xlsx from disk.
Impact on ReportConfig Deletion
A 
ReportConfig cannot be deleted while any history records reference it. This is a deliberate constraint: the history exists as a permanent trace of what was rendered using that configuration. To remove a report configuration entirely, its history records and their linked print tasks must be cleared first, either manually or by waiting for the automatic purge to run.

Scan2Print: Printing labels by scanning
Scan2Print is a dedicated, mobile-optimized page for printing labels and documents straight from a barcode scan. It is built for handheld terminals (MDE) and smartphones, but works just as well on a desktop workstation with a USB scanner. Configure the station once, then every scan becomes a print job, no forms, no clicks, no PDF preview in between.
Typical use cases are inbound goods labels, article and batch labels, inspection tags or pallet labels, anywhere a worker scans a value and needs a printed label a second later.
Screenshot placeholder: 
scan2print.index-mobile.png
Scan2Print page on a handheld (approx. 360 px width): top bar with configuration summary and gear button, two scan fields, Print button.
How It Works
Open Scan2Print from the main navigation.
On the first visit, a configuration dialog opens. Select the report, the printer, the number of copies and fill in the fixed values for this station.
The page now shows one input field per scan parameter of the report, stacked on top of each other.
Scan the values. Every scan ends with Enter, which moves the cursor to the next field. The Enter on the last field triggers the render.
VeloxFactory renders the report, creates a print task and returns to the empty scan form. The cursor is back in the first field, ready for the next scan.
Under the hood, Scan2Print uses the same rendering pipeline as the Generate PDF page and the API. Every Scan2Print submit is a regular render request with a print task attached, so everything you know about print tasks, history records and SQL data adapters applies here as well.
Permissions
Scan2Print has its own permission, found in the user settings under the section Scan2Print:
  
    
      
Permission
      
Purpose
    
  
  
    
      
scan2print:use
      
Shows the Scan2Print navigation item and grants access to the page. Administrators (
global:admin) have access automatically.
    
  
Screenshot placeholder: 
scan2print.user-permission.png
User edit page, section Scan2Print with the Use checkbox.
scan2print:use is all a scan user needs. Every Scan2Print submit runs through the regular rendering pipeline, which checks its own permissions for rendering, print tasks and history records. The Scan2Print permission therefore implicitly includes these permissions, there is no need to grant them separately:
  
    
      
Implicit permission
      
Required for
    
  
  
    
      
Report Configs: Read
      
Selecting a report and rendering it.
    
    
      
Report Print Tasks: Read and Create
      
Creating the print job after every scan and checking the print queue.
    
    
      
Report History Records: Create and Update
      
Storing the render in the report history, if enabled in the station configuration.
    
  
As a consequence, a Scan2Print user also sees the Reports and Print Queue items in the navigation and can open report configurations read-only, including their Generate PDF page.
ℹ️ Dedicated scan users land on Scan2Print directly. Users who hold 
scan2print:use but may not create or edit report configurations are redirected to Scan2Print when they open the application root. Bookmarking the Scan2Print page on the device works as well, after a login VeloxFactory returns to it automatically.
Preparing a Report for Scan2Print
Scan2Print does not need a special report type. It works with any report configuration and decides by parameter name prefix which values are scanned and which are fixed:
  
    
      
Prefix
      
Role
      
Filled in
    
  
  
    
      
P_SCAN_
      
Scan field. Appears as an input on the scan page. Always mandatory.
      
On every scan
    
    
      
P_STATIC_
      
Fixed value for the station, e.g. client name, storage location or inspector.
      
Once, in the configuration dialog
    
    
      
P_RESOURCE_
      
Image resource, handled automatically as usual.
      
Never
    
    
      
any other
      
Regular parameter. Not filled by Scan2Print, but can be delivered by the SQL query (see below).
      
Never
    
  
The scan fields appear in the order in which the parameters are declared in the 
.jrxml. The field label is derived from the parameter name, 
P_SCAN_ARTICLE_NUMBER is shown as Article Number. Scan and static fields use the same typed inputs as the Generate PDF page, a 
java.sql.Date static parameter becomes a date picker, a 
java.lang.Integer scan field a numeric input.
A minimal parameter block looks like this:
<parameter name="P_SCAN_ARTICLE_NUMBER" class="java.lang.String">
    <property name="exampleValue" value="56932.2"/>
    <property name="required" value="true"/>
</parameter>
<parameter name="P_SCAN_ARTICLE_BATCH" class="java.lang.String">
    <property name="exampleValue" value="B69854/2026"/>
    <property name="required" value="true"/>
</parameter>
<parameter name="P_STATIC_INBOUND_DATE" class="java.lang.String">
    <property name="exampleValue" value="2026-05-02"/>
    <property name="required" value="true"/>
</parameter>
Which reports can be selected
Only reports that Scan2Print can actually fill are offered in the configuration dialog. A report is selectable if all of the following apply:
It has at least one 
P_SCAN_ parameter.
None of its 
P_SCAN_ parameters is of type 
java.lang.Boolean, a toggle cannot be scanned.
It has no detail band, or it has an SQL data adapter. Scan2Print never sends report lines, so detail data can only come from a query.
It has no required parameter outside 
P_SCAN_ and 
P_STATIC_, because Scan2Print has no way to fill it.
If your report does not show up in the dropdown, check it against this list first.
Enriching the label with SQL
The real strength of Scan2Print comes with an SQL data adapter. Scan only the key, for example an article number, and let the query fetch everything else. Scan values are available in the query like any other parameter, and every column aliased with a parameter name is transferred into that parameter:
select
    a.description as 'P_ARTICLE_DESCRIPTION'
  , b.barcode     as 'P_ARTICLE_BARCODE'
  , a.supplier    as 'P_ARTICLE_SUPPLIER'
from article a
inner join articlebarcode b on a.id = b.articleId
where a.articleNumber = :P_SCAN_ARTICLE_NUMBER
Parameters that are filled by the query must be marked as not required in the 
.jrxml. VeloxFactory validates required parameters before the query runs, so a required parameter that only the query delivers would always fail.
ℹ️ A query must return at least one row. If a report has an SQL data adapter and the query finds nothing, for example because an unknown article number was scanned, the render fails with "No data delivered (or fetched via SQL using parameters)...". No print task is created, so no half-empty label is printed. If the query returns several rows, the values of the last row are used for the parameters.
Configuring the Scan Station
The configuration dialog opens automatically when no configuration exists yet. Afterwards, it can be reopened at any time with the gear button in the top bar of the page, which also shows a compact summary of the active configuration (report, printer, copies, broadcast ID and static values).
  
    
      
Option
      
Default
      
Description
    
  
  
    
      
Report
      
-
      
Searchable list of all Scan2Print capable reports. Required.
    
    
      
Printer Name
      
-
      
The target printer for every print task of this station. Required.
    
    
      
Copies
      
1
      
Number of copies per scan, between 1 and 100.
    
    
      
Broadcast ID
      
-
      
Optional WebSocket channel ID for real-time notification of the print service. Leave empty to rely on polling.
    
    
      
Create History Record
      
On
      
Stores every scan render in the report history, including request, response and PDF. Can be switched off for high-volume stations.
    
    
      
Static Parameters
      
-
      
One typed input per 
P_STATIC_ parameter of the selected report. They are loaded as soon as a report is selected and replaced when you switch to another report. All of them are required, except boolean toggles.
    
  
Screenshot placeholder: 
scan2print.config-modal.png
Configuration dialog with selected report, printer, copies, broadcast ID, history toggle and loaded static parameters.
Click Save to store the configuration. If something is missing or invalid, VeloxFactory shows an error message and reopens the dialog with your input still in place.
To reset the station, open the dialog and click Clear configuration. The scan form disappears and the dialog asks for a new configuration.
ℹ️ Static values are fixed. A static date stays exactly as entered, it does not move on to the next day. If a label should always show the current date, use a default expression in the 
.jrxml instead of a static parameter.
Scanning and Printing
With a valid configuration, the page shows all scan fields of the report, large and full width, with the cursor already in the first field.
Enter in a filled field moves the cursor to the next field and selects its content.
Enter in the last field submits the form and starts the render.
Enter in an empty field does nothing, the cursor stays where it is. All scan fields are mandatory.
The Print button below the fields submits the form as well, which is handy for manual input on a desktop.
Screenshot placeholder: 
scan2print.scan-form.png
Scan form on desktop with a configured report, cursor in the first scan field.
After submitting, the form is locked until the page has reloaded. Scanners that send their data in quick bursts or add an extra Enter therefore never create duplicate print jobs. Reloading the page after a print does not print again either.
The Result
Success
A short green notification confirms the print job for two seconds, including report name, printer and number of copies. The scan fields are empty again and the cursor is back in the first field. The print task is now in the print queue and will be picked up by the print service.
Screenshot placeholder: 
scan2print.result-success.png
Green notification after a successful scan, empty scan fields.
Errors
If the render fails, a red block appears in the page body. It stays visible until the next scan and contains:
all error messages returned by VeloxFactory, e.g. an unknown article number or a missing value,
the values that were scanned, so the worker knows which item failed,
a link to the print queue.
The scan fields are cleared and the cursor is back in the first field, so the worker can simply scan again.
Screenshot placeholder: 
scan2print.result-error.png
Red error block with error message (e.g. unknown article number), scanned values and link to the print queue.
ℹ️ Check the print queue before rescanning after a WebSocket error. If the broadcast to the print service fails, for example because Reverb is not running, the print task has already been created and is still printed by polling. Scan2Print shows an error in this case, a rescan would print the label twice.
Where the Configuration Is Stored
The station configuration is stored in the user session on the server. This keeps each device independent, two handhelds logged in with different users can serve different reports and printers at the same time.
The configuration survives page reloads and navigation within VeloxFactory.
It is removed on logout and when the session expires after the configured idle time (
SESSION_LIFETIME). The worker then logs in again and reconfigures the station. After a session timeout, a pending scan cannot be submitted anymore and the page has to be reloaded.
Static values are stored by parameter name. If the report is deleted, loses its Scan2Print capability, or a new 
.jrxml with additional required static parameters is uploaded, the configuration is reset automatically on the next page load, a warning is shown and the configuration dialog opens.
Scanner Requirements and Tips
Scan2Print expects a scanner in keyboard mode (keyboard wedge), as used by nearly all handheld terminals and USB scanners.
Configure the scanner to send Enter as suffix. A Tab suffix only moves the cursor and never submits the form.
Camera scanning is not part of Scan2Print. Smartphones need a hardware scanner or a scanner app that types into the focused field.
On smartphones, the on-screen keyboard opens when a field is focused. This is intended, it keeps manual input possible.
For barcodes on the printed label, prefer Code128 when the label should reproduce the scanned value exactly. EAN-13 components pad shorter values such as EAN-8 codes with zeros and recalculate the check digit, so the printed barcode would differ from the scanned one.

Print your renderings
Getting a rendering onto paper: print tasks, printer master data and our own print service.

Creating Report Print Tasks
A 
ReportPrintTask represents a single print job, a PDF queued for delivery to a physical printer. VeloxFactory does not communicate with printers directly. Instead, it creates the task record, optionally notifies a separate print service via WebSocket, and waits for the service to report back. This page covers how tasks are created, how the status lifecycle works, and how to handle retries. Its counterpart for the other delivery route is the 
ReportMailTask, described on Report Mailing: same idea, same three ways to be created, a mailbox instead of a printer.
Screenshot placeholder: 
report-print-task.index.png
Report Print Task overview with status badges, printer and the reset action.
Three Ways to Create a Print Task
1. As Part of a Render Request
The most common path: set 
createPrintTask: true in the render request body, provide a 
printerName, and VeloxFactory renders the report and dispatches it to the printer in a single call. No second request needed.
POST /api/v1/report-config/A5_KanBan/render
{
  "outputType": "base64",
  "parameters": { "P_ARTICLE_NUMBER": "4561287-154" },
  "data": [ { ... } ],
  "createHistoryRecord": true,
  "createPrintTask": true,
  "printerName": "WarehousePrinter01",
  "numberOfCopies": 1,
  "broadcastId": "Standard"
}
2. From a History Record
A task can be dispatched from any existing 
ReportHistoryRecord, without re-rendering the report. VeloxFactory uses the PDF stored in the history record and creates a new print task from it:
POST /api/v1/report-history-record/{id}/print
{
  "printerName": "WarehousePrinter01",
  "numberOfCopies": 2
}
This is the standard reprint path. See The concept of Report History Records for details.
3. Standalone via the Print Task API
Print tasks can also be created directly, independently of any render or history record. The 
POST /api/v1/report-print-task endpoint accepts any PDF as a Base64 string, making it possible to use the VeloxFactory print infrastructure for documents that were not produced by VeloxFactory at all.
POST /api/v1/report-print-task
{
  "fileName":       "delivery_note_5521.pdf",
  "fileBase64":     "JVBERi0xLjQ...",
  "printerName":    "WarehousePrinter01",
  "numberOfCopies": 1,
  "broadcastId":    "Standard"
}
reportConfig and 
reportHistoryRecord are both optional on this endpoint, the task is created without either relation if they are not provided.
The Data Model
  
    
      
Field
      
Description
    
  
  
    
      
traceId
      
Unique identifier. Shared with the linked history record when the task was created via a render request. For reprints, a derived trace ID is generated (original + short random suffix).
    
    
      
reportConfig
      
The 
ReportConfig the printed PDF was generated from. Optional, not present for standalone tasks.
    
    
      
reportHistoryRecord
      
The linked 
ReportHistoryRecord. Optional, not present for standalone tasks.
    
    
      
printerName
      
The name of the target printer, as the print service expects it.
    
    
      
numberOfCopies
      
Number of copies passed to the print service. VeloxFactory always renders once, the print service is responsible for duplication. Defaults to 
1.
    
    
      
broadcastId
      
WebSocket channel ID. If set at creation time, VeloxFactory broadcasts a 
ReportPrintTaskCreated event via Laravel Reverb. Omit to use polling instead.
    
    
      
outputFileName
      
The filename of the PDF queued for printing.
    
    
      
status
      
Current state of the task. See below.
    
    
      
errorMessage
      
Failure detail reported by the print service. 
null unless status is 
error.
    
  
Status Lifecycle
Every print task starts as 
pending. The print service picks it up, executes the job, and reports the result back to VeloxFactory via the API:
  
    
      
Status
      
Set by
      
Meaning
    
  
  
    
      
pending
      
VeloxFactory
      
Task created, waiting for the print service to pick it up.
    
    
      
printed
      
Print service
      
Print job executed and confirmed.
    
    
      
error
      
Print service
      
Print job failed. 
errorMessage contains the failure detail.
    
    
      
unknown
      
-
      
Status could not be determined.
    
  
The print service reports back using the dedicated status endpoint:
PATCH /api/v1/report-print-task/{id}/set-status
{
  "status": "error",
  "errorMessage": "Printer offline"
}
Resetting to Pending
A task can be reset to 
pending using the set-printed shortcut endpoint, setting the status flag to 
false:
PATCH /api/v1/report-print-task/{id}/set-printed/false
This re-queues the task. If the task has a 
broadcastId, VeloxFactory re-broadcasts the 
ReportPrintTaskCreated event immediately, notifying the print service to pick the task up again without polling. This is the standard retry mechanism for failed or stalled print jobs.
WebSocket vs. Polling
How the print service learns about a new task depends on whether a 
broadcastId is set.
With 
broadcastId: VeloxFactory broadcasts a 
ReportPrintTaskCreated event via WebSocket (Laravel Reverb) the moment the task is created. The print service subscribes to the channel identified by 
broadcastId and reacts immediately. This is the recommended mode for real-time printing, the task reaches the printer within milliseconds of the render completing.
Without 
broadcastId: No broadcast is sent. The print service must poll 
GET /api/v1/report-print-task?status=pending at a regular interval and process any tasks it finds. This works fine for workflows where sub-second delivery is not required.
Each poll returns one page of the waiting tasks, oldest first: 25 by default, up to 100 with 
perPage. A poller that reports every task back via 
set-status can simply request the first page again, finished tasks drop out of the 
pending filter by themselves. 
meta.pagination.total tells how many tasks are still waiting, see Pagination.
ℹ️ WebSocket delivery requires Laravel Reverb to be running. If Reverb is down, task creation will fail with an error rather than falling back silently to polling. Use Supervisor to keep the Reverb process alive, the same Supervisor configuration that manages the Laravel queue worker should include a 
php artisan reverb:start program entry. See Installing VeloxFactory for a reference configuration.
Retention and Deletion
Print tasks are automatically purged after a configurable number of days, set via the 
PURGE_PRINTTASKS_DAYS environment variable (default: 30 days). Purging runs as a scheduled background job, no manual action required.
Individual tasks can also be deleted directly via the API at any time:
DELETE /api/v1/report-print-task/{id}
There are no deletion constraints on print tasks themselves, they can always be removed. However, deleting a print task is a prerequisite for deleting the linked 
ReportHistoryRecord, which in turn must be cleared before a 
ReportConfig can be deleted. Mail tasks block a history record in exactly the same way and have their own retention setting, 
PURGE_MAILTASKS_DAYS. Automatic purging handles the whole chain in the background once the retention periods expire.

Printers: master data for your print targets
A print task needs to know where it should come out. That destination is a queue name on the print server: exact, unforgiving and easy to mistype, and a typo is only noticed when nothing comes out of the printer. Printers turn that string into master data: a short list of the machines your company actually prints on, each with a readable name, a location and, if you use the WebSocket print service, its broadcast ID.
The print service itself sees none of that. VeloxFactory hands it the queue name of the printer and nothing else. The master data only decides which queue name is sent, and it lets everyone else work with names a human recognises.
Screenshot placeholder: 
printer.index.png
Printer overview under Configuration with filter bar, type badges and the Active column.
Where to find it
The printer master data lives in the main menu under Configuration → Printers. The overview is a regular VeloxFactory lookup: search over display name, queue name, location and description, filters for type, active state, creator, updater and the creation date, and sortable columns. Like every lookup, the filter settings and the current page are kept in your session, so you come back to the list exactly as you left it.
New opens the create form, the pencil on a row opens an existing record. Deleting is done from the edit page.
The fields of a printer
  
    
      
Field
      
Required
      
Description
    
  
  
    
      
Display Name
      
yes
      
The name people use, for example 
Warehouse Label 01. Three to 50 characters and unique across all printers.
    
    
      
Printer Name
      
yes
      
The queue name on the print server, for example 
WH-LABEL-01. This is the value the print service receives. Up to 50 characters and unique as well.
    
    
      
Printer Type
      
yes
      
One of 
label-printer, 
a4-printer, 
mfc-printer or 
digital-printer. Purely descriptive, it drives the icon and the filter, not the rendering.
    
    
      
Location
      
no
      
Where the machine stands, for example 
Hall 2, Shipping. Shown in the picker so a station is easy to identify.
    
    
      
Broadcast ID
      
no
      
The WebSocket channel of the print service instance that serves this printer. Set it once here and no one has to remember it again.
    
    
      
Description
      
no
      
Free note, for example the label size or the media currently loaded.
    
    
      
Active
      
-
      
On by default. Inactive printers stay in the master data and keep working in existing configurations, but they are not offered in the pickers.
    
  
ℹ️ Retiring a printer is a toggle, not a delete. Switch it to inactive and it disappears from every picker while the print tasks that reference it keep their history.
Screenshot placeholder: 
printer.edit.png
Printer edit form with display name, queue name, type, location, broadcast ID, description and the Active toggle.
Name resolution
This is the part that makes the master data useful everywhere, including in scripts that know nothing about it. Whenever VeloxFactory receives a printer name, from the frontend, from the API or from an AI assistant, it resolves that name before the print task is stored:
The name is compared to the queue name of every printer record, ignoring upper and lower case.
If nothing matches, it is compared to the display name.
If a record matches, its queue name is stored on the print task, and its broadcast ID is filled in unless the caller sent one explicitly.
If nothing matches, the name is stored exactly as supplied.
  
    
      
You send
      
Stored printer name
      
Stored broadcast ID
    
  
  
    
      
WH-LABEL-01
      
WH-LABEL-01
      
from the record, if it has one
    
    
      
Warehouse Label 01
      
WH-LABEL-01
      
from the record, if it has one
    
    
      
warehouse label 01
      
WH-LABEL-01
      
from the record, if it has one
    
    
      
SOME-OTHER-QUEUE
      
SOME-OTHER-QUEUE
      
only what you sent
    
  
Resolution runs on every path that accepts a printer name: rendering a report configuration with Create Print Task, creating or updating a print task directly, printing a stored history record again, and every Scan2Print scan. A broadcast ID you send yourself always wins over the one stored on the record.
ℹ️ A plain queue name is always accepted. An integration that sends the queue name gets exactly the printer it asked for, with the broadcast ID filled in from the record if the printer has one. Nothing has to know that the master data exists.
The printer picker
Wherever a printer is chosen, VeloxFactory shows the same control: a searchable dropdown of all active printers above a plain text field. The dropdown entries read 
Display Name (queue name) - location, and picking one writes the queue name into the text field and fills a neighbouring Broadcast ID field if the printer has one. The text field stays editable, so a printer that is not in the master data can still be addressed by typing its name.
The picker appears in four places:
the Output Settings of the Generate PDF page
the Configuration dialog of Scan2Print
the edit dialog of a Report Print Task
the print dialog of a Report History Record
If no printers are configured at all, the picker silently falls back to a plain text field with the note No printers configured yet. The master data is optional: an instance without a single printer record addresses its printers by typing the queue name.
Print tasks and the printer link
Every print task keeps its printer name as text, that text is what the print service consumes. In addition, a print task whose name resolved to a master data record stores a reference to that record. This link is used for one thing only: the print queue can be filtered by printer, including the entry Not linked to a printer for everything that was addressed by free text.
Deleting a printer record therefore never touches history. The print tasks keep their stored printer name, they only lose the link, and the filter moves them to Not linked to a printer.
The API
Printers are a regular API resource under 
/api/v1/printer, with the same envelope, the same audit segment and the same error format as every other resource.
  
    
      
Endpoint
      
Description
    
  
  
    
      
GET /printer
      
List printers page by page with 
page and 
perPage (see Pagination), optionally narrowed with 
isActive and 
printerType.
    
    
      
GET /printer/{id}
      
A single printer, with 
withAudit=true including its audit segment.
    
    
      
POST /printer
      
Create a printer. 
displayName, 
printerName and 
printerType are required, both names must be unique.
    
    
      
PATCH /printer/{id}
      
Partial update: fields you do not send keep their stored value.
    
    
      
DELETE /printer/{id}
      
Delete a printer. Existing print tasks keep their stored printer name.
    
  
A printer resource is returned as:
{
    "model": "Printer",
    "id": 1,
    "displayName": "Warehouse Label 01",
    "location": "Hall 2, Shipping",
    "printerName": "WH-LABEL-01",
    "printerType": "label-printer",
    "printerTypeLabel": "Label Printer",
    "broadcastId": "Standard",
    "isActive": true,
    "description": "4x6\" thermal labels"
}
AI assistants
The VeloxFactory MCP server exposes the same five operations as tools: 
list_printers, 
get_printer, 
create_printer, 
update_printer and 
delete_printer. Because name resolution happens inside VeloxFactory, an assistant can simply pass the name a person said. Print this on the warehouse label printer is enough, no lookup up front.
Permissions
Printers use the standard permission scheme. In the user editor they have their own Printers section.
  
    
      
Permission
      
Grants
    
  
  
    
      
printer:read
      
See the menu entry, the overview and a printer's detail page.
    
    
      
printer:create
      
Create printers.
    
    
      
printer:update
      
Change printers, including the active state.
    
    
      
printer:delete
      
Delete printers.
    
    
      
printer:full
      
All of the above, like 
global:admin.
    
  
The picker itself needs no printer permission. A user who may only scan labels still sees the configured printers in the Scan2Print dialog, they just cannot open or change the master data.

VeloxFactory Print Service
Our Windows print service: installation, configuration, printing, the window, the command line and monitoring.

The Print Service: VeloxFactory on your printers
VeloxFactory does not talk to printers directly. A companion Windows application, the VeloxFactory Print Service, runs on any machine that has the target printers installed. It receives print tasks from VeloxFactory, prints the PDF on the right printer and reports the result back. Both sides communicate only over the VeloxFactory REST API and the WebSocket server (Laravel Reverb). There is no shared database and no shared file system.
This chapter describes version 2.0.
At a glance
  
    
      
One program, two ways to run
      
Started without parameters it opens a window with dashboard, live console, job history, printer overview, statistics and settings. Started with 
--headless the same program runs without any window from the Windows Task Scheduler, whether a user is logged on or not.
    
    
      
Reliable receiving
      
WebSocket events for speed, a safety poll against lost events, automatic polling while the WebSocket is down. Only tasks of the own broadcast ids are taken.
    
    
      
No double prints
      
A local job journal remembers every task. A task that reached the Windows spooler is never printed a second time, even after a crash or a lost confirmation.
    
    
      
Sharp output
      
PDFium draws every page directly onto the printer in its native resolution. Text, lines and barcodes stay vector graphics, nothing is rasterised in between.
    
    
      
Rate limit aware
      
Reads the rate limit headers of the API. On HTTP 429 every API call pauses until 
Retry-After, print tasks wait instead of failing.
    
    
      
Nothing on disk
      
PDFs stay in memory. The API token is stored encrypted (DPAPI) and separate from the configuration.
    
    
      
Operable
      
Rolling log files, Windows event log with fixed event ids, optional local health endpoint, diagnostic package, graceful stop for updates.
    
  
How it works
VeloxFactory                               Print Service (Windows)
------------                               -----------------------
Print task created  -- WebSocket event -->  Receiver (WebSocket / poll)
                    <-- GET task + PDF ---  Journal: known task? skip
                                            Worker -> printer lock -> PDFium -> Windows spooler
                    <-- set-printed -------  Outbox (retried until delivered)
                    <-- set-status error --  on permanent failures
Receive. A new print task triggers the WebSocket event 
report-print-task.created on the private channel 
private-report-print-tasks. The event only carries the task id and the broadcast id. In addition, the service polls the pending tasks of its broadcast ids (details in Receiving and processing print tasks).
Fetch. The service loads the task including the PDF (
withMedia=true). The printer machine therefore needs HTTP access to VeloxFactory, not only WebSocket access.
Deduplicate. The job journal decides whether the task is new. Known tasks are skipped.
Print. A worker takes the task, waits for the printer if another job is running on it, checks the Windows queue (offline, paper out) and prints. Transient problems are retried.
Confirm. Success is written to the outbox first and then sent with 
PATCH /api/v1/report-print-task/{id}/set-printed. If VeloxFactory is unreachable, the outbox retries until it succeeds. Permanent failures are reported with 
set-status and a categorised error message.
Operating modes
  
    
      
Mode
      
Started by
      
Behaviour
    
  
  
    
      
Headless
      
--headless, normally from the scheduled task
      
The engine runs without any window. This is the production mode.
    
    
      
Monitor
      
Program started without parameters while a headless engine runs
      
The window shows state, console, jobs and statistics of the headless engine and edits its configuration. It does not print itself.
    
    
      
Interactive
      
Program started without parameters, no engine running
      
The engine runs inside the window. Closing the window keeps it running in the notification area. Useful for setup, tests and machines without scheduled task.
    
  
A named mutex per instance makes sure only one engine runs. The window detects a running headless engine automatically and switches to monitor mode.
ℹ️ Several instances per machine. With 
--config <path> every instance gets its own configuration, token, journal, logs and scheduled task. Use one instance per broadcast id or site. Two instances listening to the same broadcast id would both print the same task, the journal only protects within one instance.
In this chapter
  
    
      
Installation and updates
      
Requirements, folder layout, service account, scheduled task, update and rollback
    
    
      
Configuration reference
      
Every key of 
config.json with default and range, token, hot reload, import and export
    
    
      
Receiving and processing print tasks
      
Receive modes, broadcast ids, rate limit, pipeline, retries, pause, journal, outbox, dry run
    
    
      
Printers and printing
      
Printer comparison, alias, per-printer settings, dialog printers, test page
    
    
      
The Print Service window
      
Dashboard, console, jobs, printers, statistics, settings, info, tray icon
    
    
      
Command line reference
      
All parameters, exit codes and examples
    
    
      
Monitoring and troubleshooting
      
Log files, event ids, health endpoint, diagnostic package, common problems
    
    
      
Open Source Attribution
      
Bundled packages and their licenses

Installation and updates
The Print Service has no installer. The program is delivered as a git repository that contains only the released build. Updates are a 
git checkout, driven by a script that stops the service gracefully first. Configuration, token, job journal and logs live in a separate data folder and survive every update.
Requirements
  
    
      
Operating system
      
Windows 10/11 or Windows Server 2019 or newer, x64
    
    
      
Runtime
      
.NET 10 Desktop Runtime (x64). The build is framework-dependent, the runtime is not bundled.
    
    
      
Git
      
Git for Windows and read access to the release repository
    
    
      
Network
      
HTTPS to the VeloxFactory API and WSS to the Reverb server of your instance. With receive mode 
Polling the API alone is enough.
    
    
      
API token
      
Token of a user with 
global:use-api, 
report-print-task:read and 
report-print-task:update. 
printer:read is optional and enables the printer comparison. 
:read is also the right the private channel checks, a token without it never receives a WebSocket event.
    
    
      
Service account
      
A dedicated Windows account for the scheduled task, see below
    
    
      
Printers
      
Installed machine-wide, see Printers and printing
    
  
Folder layout
C:\kiwisoftware\VeloxPrint\
  app\          clone of the release repository, program only, updated by update.ps1
    bin\        kiwisoftware.VeloxFactory.PrintService.App.exe and its libraries
    update.ps1
    README.md
  data\         created by the app, never part of git
    config.json     configuration without token
    secrets.json    API token, encrypted
    state.db        job journal, outbox, statistics, log buffer, engine status (SQLite)
    logs\           rolling log files
Where the data folder is:
--config <path> sets it explicitly: all files of the instance live next to that configuration file.
If the program runs from a folder named 
app or below it, the data folder is 
data next to that 
app folder.
Otherwise it is 
%ProgramData%\kiwisoftware\VeloxPrint\.
  
    
      
File
      
Permissions
    
  
  
    
      
config.json
      
Administrators and service account: modify. Users: read.
    
    
      
secrets.json
      
Administrators and service account: modify. Users: no access.
    
    
      
state.db, 
logs\
      
Service account: modify. Users: read.
    
  
The first start with administrator rights creates the data folder and sets these permissions. Setting up the scheduled task adds the service account.
⚠️ Do not copy 
secrets.json to another machine. The token is encrypted with DPAPI for this machine (scope LocalMachine), so the window of an administrator and the headless service account can both read it. On another machine it cannot be decrypted, enter the token there again.
First installation
1. Create the service account
The scheduled task runs under its own account. It must exist before the task is set up, the Print Service does not create it. PowerShell as administrator:
$pw = Read-Host -AsSecureString "Password"
New-LocalUser -Name "svc-veloxprint" -Password $pw -FullName "VeloxFactory Print Service" `
  -Description "Service account VeloxFactory Print Service" -PasswordNeverExpires -UserMayNotChangePassword
Do not add the account to the Administrators group, the standard Users group is enough.
Use 
-PasswordNeverExpires. An expired password stops the task until it is set up again.
For printers on a print server in a domain, use a domain account (
DOMAIN\svc-veloxprint) instead. Only a domain account can authenticate at the print server.
Do not use 
SYSTEM. It accesses print servers with the computer account, shares often refuse that.
2. Clone the release
PowerShell as administrator:
New-Item -ItemType Directory C:\kiwisoftware\VeloxPrint
git clone https://git.fischernetz.xyz/bfischer/veloxfactory-printservice-release.git C:\kiwisoftware\VeloxPrint\app
3. Configure
Start 
C:\kiwisoftware\VeloxPrint\app\bin\kiwisoftware.VeloxFactory.PrintService.App.exe as administrator. The first elevated start creates 
data\ and restricts its permissions.
Settings → Connection: base URL of VeloxFactory and API token. Test connection checks reachability, token, channel authorization, WebSocket handshake and rate limit headers.
Settings → WebSocket (Reverb): host, port, scheme and app key of your Reverb server.
Settings → Receiving: the broadcast ids of this site.
Save. See the Configuration reference for every setting.
4. Set up the scheduled task
Settings → Operation → Set up scheduled task, enter the service account (
.\svc-veloxprint for a local account) and its password. Alternatively on the command line (as administrator):
& "C:\kiwisoftware\VeloxPrint\app\bin\kiwisoftware.VeloxFactory.PrintService.App.exe" --install-task --user .\svc-veloxprint
The setup:
grants the account the right Log on as a batch job,
sets the permissions of the data folder and 
secrets.json for the account,
registers the Windows event log source VeloxFactory Print Service,
creates or updates the task with the settings below.
  
    
      
Task setting
      
Value
      
Reason
    
  
  
    
      
Name
      
VeloxFactory Print Service, for an alternative configuration 
VeloxFactory Print Service (<config name>)
      
Root folder of the Task Scheduler library
    
    
      
Run
      
Whether the user is logged on or not, password stored
      
No desktop needed; without stored password network printers are unreachable
    
    
      
Trigger
      
At system start, delayed 1 minute
      
Network and spooler are ready
    
    
      
Action
      
--headless (plus 
--config for an alternative instance), start in the program folder
      
The Task Scheduler would otherwise start in 
System32
    
    
      
Time limit
      
None
      
The Windows default of 3 days would end the engine
    
    
      
On failure
      
Restart every minute, up to 999 times
      
Crash recovery
    
    
      
Already running
      
Do not start a new instance
      
In addition to the instance mutex
    
    
      
Privileges
      
Not elevated
      
Not needed
    
    
      
Battery
      
Runs on battery, starts when available
      
Missed starts are caught up
    
  
⚠️ Do not edit the task by hand. Setting it up again from the window or with 
--install-task overwrites it with the values above. After changing the password of the service account, set the task up again, the password is stored in the task.
The window shows the task under Settings → Operation: state, account, last and next run, last result and the XML definition. It can start and remove the task there, too.
5. Verify
Printers: print a test page on every printer the site uses.
Start the task (Settings → Operation → Start or reboot). The window switches to monitor mode.
Create a print task in VeloxFactory for one of the broadcast ids and watch it on the Dashboard.
Updates and rollback
PowerShell as administrator:
# newest release
powershell -ExecutionPolicy Bypass -File C:\kiwisoftware\VeloxPrint\app\update.ps1
# a specific release, also the way back to an older one
powershell -ExecutionPolicy Bypass -File C:\kiwisoftware\VeloxPrint\app\update.ps1 -Version 2.0.1
  
    
      
Step
      
What 
update.ps1 does
    
  
  
    
      
1. Check
      
Refuses to run without administrator rights or if 
app\ contains local changes
    
    
      
2. Fetch
      
git fetch before anything is stopped. If the server is unreachable, the service keeps running. Already on the target: nothing to do.
    
    
      
3. Stop
      
Calls 
--stop for every scheduled task that runs from this folder (with its 
--config). Running print jobs finish, the outbox is flushed. Waits up to 90 s until no process runs from 
app\bin.
    
    
      
4. Switch
      
Checks out the newest release (
origin/main) or the tag 
v<Version>
    
    
      
5. Start
      
Starts the scheduled tasks again that were running before
    
  
Releases are git tags (
v2.0.1). 
git -C C:\kiwisoftware\VeloxPrint\app log --oneline shows the source commit of every release.
New settings are added to 
config.json with their defaults on the next start.
Never change files inside 
app\. The script refuses to update a modified folder. Settings belong into 
data\.
Several instances on one machine
Each instance needs its own configuration file. Its name becomes the prefix of all files of the instance, so several instances can share one data folder:
data\config.json               default instance
data\lager-nord.json           second instance
data\lager-nord.secrets.json
data\lager-nord.state.db
data\logs\lager-nord\
$exe = "C:\kiwisoftware\VeloxPrint\app\bin\kiwisoftware.VeloxFactory.PrintService.App.exe"
& $exe --config C:\kiwisoftware\VeloxPrint\data\lager-nord.json                                   # window of this instance
& $exe --config C:\kiwisoftware\VeloxPrint\data\lager-nord.json --install-task --user .\svc-veloxprint
The task of that instance is called 
VeloxFactory Print Service (lager-nord). Give every instance its own broadcast ids.

Configuration reference
All settings of an instance live in 
config.json in the data folder (see Installation and updates). The API token is not part of it, it is stored encrypted in 
secrets.json. Normally you edit everything in the window under Settings. The file can also be edited in a text editor, the running engine picks up the change by itself.
How the configuration is handled
  
    
      
Hot reload
      
The engine watches the file and applies changes without restart. A new URL, token or WebSocket setting triggers a reconnect, running print jobs finish. Exception: of the 
logging settings only 
minimumLevel applies immediately; retention, file size, event log and JSON file take effect after a restart.
    
    
      
Validation
      
On load and before saving. The window shows errors per field. A headless start with an invalid file ends with exit code 1. An invalid change while the engine runs is not applied, the engine keeps the last valid configuration and writes event id 5000.
    
    
      
New keys
      
After an update the service adds keys of the new version with their defaults and writes the file (if it may). Unknown keys are reported in the log and removed on the next save.
    
    
      
Change log
      
Every save is recorded with Windows account, time and changed keys in 
state.db. The diagnostic package contains the last 500 changes.
    
    
      
Export and import
      
Settings → Import and export. The export never contains the token. The import keeps name and id of the receiving instance, check and save afterwards. Useful to roll out one configuration to several sites.
    
    
      
Write access
      
Saving needs write access to the data folder. Without it the window offers Restart as administrator.
    
  
Example
{
  "schemaVersion": 1,
  "instance": { "id": "5d0c2f4e-...", "name": "Warehouse North", "serviceAccount": "SRV01\\svc-veloxprint" },
  "api": { "baseUrl": "https://vf.example.com", "timeoutSeconds": 30, "allowUnencrypted": false, "serverTimeZone": "Europe/Berlin" },
  "receive": {
    "mode": "Hybrid",
    "broadcastIds": ["Standard", "Warehouse"],
    "includeWithoutBroadcastId": false,
    "pollingIntervalSeconds": 30,
    "safetyPollIntervalSeconds": 120,
    "pageSize": 10
  },
  "websocket": { "scheme": "wss", "host": "vf.example.com", "port": 443, "appKey": "your-reverb-app-key", "channel": "private-report-print-tasks" },
  "processing": {
    "paused": false, "pauseReason": null, "pausedUntil": null,
    "maxParallelJobs": 4,
    "serializePerPrinter": true,
    "retryCount": 3,
    "retryBackoffSeconds": [5, 30, 120],
    "printTimeoutSeconds": 120,
    "confirmation": "Spooled",
    "dryRunFolder": null
  },
  "printerDefaults": { "scaling": "ActualSize", "autoRotate": true, "dpi": null, "copiesMode": "Driver", "paperSource": null, "duplex": "Default", "color": "Default" },
  "printers": [
    { "queueName": "WH-LABEL-01", "localName": "\\\\printsrv01\\WH-LABEL-01", "dpi": 300 },
    { "queueName": "PDF24", "copiesMode": "Loop" }
  ],
  "logging": { "minimumLevel": "Information", "retentionDays": 30, "maxFileSizeMb": 250, "eventLog": true, "jsonFile": false },
  "statistics": { "retentionDays": 365, "resetAt": null },
  "health": { "enabled": false, "port": 8765 },
  "ui": { "errorNotifications": true, "windowWidth": null, "windowHeight": null, "windowMaximized": false }
}
instance
  
    
      
Key
      
Default
      
Description
    
  
  
    
      
id
      
new GUID
      
Identifies the instance (mutex, stop signal). Never copy it to another instance, an import keeps the local id.
    
    
      
name
      
machine name
      
Display name in the window, on the test page and in the diagnostic package
    
    
      
serviceAccount
      
null
      
Account of the scheduled task, written when the task is set up. Used for the file permissions.
    
  
api
  
    
      
Key
      
Default
      
Description
    
  
  
    
      
baseUrl
      
empty, required
      
Base URL of VeloxFactory without 
/api/v1, e.g. 
https://vf.example.com. All endpoints are derived from it.
    
    
      
timeoutSeconds
      
30 (5 to 300)
      
Timeout of a single API call
    
    
      
allowUnencrypted
      
false
      
Allows 
http:// and 
ws://. Without it both are rejected, because token and PDFs would travel unencrypted. The window shows a warning banner while it is on.
    
    
      
serverTimeZone
      
Europe/Berlin
      
Time zone of the VeloxFactory instance (
APP_TIMEZONE). Audit timestamps of the API carry no offset, the lead time statistics need it.
    
  
The API token is entered in Settings → Connection and stored in 
secrets.json. Required rights: 
global:use-api, 
report-print-task:read, 
report-print-task:update, optional 
printer:read. The token never appears in logs, exports or diagnostic packages.
receive
  
    
      
Key
      
Default
      
Description
    
  
  
    
      
mode
      
Hybrid
      
Hybrid, 
WebSocket or 
Polling, see Receiving and processing print tasks
    
    
      
broadcastIds
      
[]
      
Broadcast ids this instance prints, exact match. At most 20, unique, no commas, no surrounding spaces, max. 255 characters. At least one is required unless 
includeWithoutBroadcastId is on.
    
    
      
includeWithoutBroadcastId
      
false
      
Also take tasks and printers without broadcast id. VeloxFactory sends no WebSocket event for such tasks, they arrive only by polling (in Hybrid after at most 
safetyPollIntervalSeconds). Turn it on in one instance at most.
    
    
      
pollingIntervalSeconds
      
30 (min. 1)
      
Poll interval in mode 
Polling, and in 
Hybrid while the WebSocket is down. Below 3 s the window warns: constant API calls, the rate limit is used up quickly.
    
    
      
safetyPollIntervalSeconds
      
120 (min. 30)
      
Safety poll in 
Hybrid while the WebSocket is subscribed
    
    
      
pageSize
      
10 (1 to 100)
      
Tasks per poll page. Every page carries the PDFs, a small value keeps responses small. Further pages follow immediately.
    
  
websocket
Ignored in mode 
Polling. The URL is built as 
{scheme}://{host}:{port}/app/{appKey}?protocol=7&client=veloxprint&version={x}.
  
    
      
Key
      
Default
      
Description
    
  
  
    
      
scheme
      
wss
      
wss or 
ws (
ws only with 
api.allowUnencrypted)
    
    
      
host
      
empty, required
      
Host of the Reverb server as reachable from the printer machine (
REVERB_HOST)
    
    
      
port
      
443
      
Port of the Reverb server (
REVERB_PORT, behind a reverse proxy usually 443)
    
    
      
appKey
      
jasper-who
      
REVERB_APP_KEY of your VeloxFactory instance
    
    
      
channel
      
private-report-print-tasks
      
Private channel of the print task events. Must start with 
private-. Keep the default.
    
  
processing
  
    
      
Key
      
Default
      
Description
    
  
  
    
      
paused, 
pauseReason, 
pausedUntil
      
false, null, null
      
Maintenance pause. With 
pausedUntil (ISO 8601 with offset) the pause ends by itself. Survives a restart.
    
    
      
maxParallelJobs
      
4 (1 to 32)
      
Tasks processed at the same time
    
    
      
serializePerPrinter
      
true
      
One job per printer at a time, in the order of the task ids
    
    
      
retryCount
      
3 (0 to 10)
      
Local retries on transient errors (printer offline, paper out, spooler refused the job)
    
    
      
retryBackoffSeconds
      
[5, 30, 120]
      
Wait before retry 1, 2, 3 and so on (1 to 3600 each). With more retries than values the last value repeats.
    
    
      
printTimeoutSeconds
      
120 (10 to 3600)
      
Limit for a print call and for the spooler wait of 
Completed. A driver that waits for a dialog ends here.
    
    
      
confirmation
      
Spooled
      
Spooled: confirm after handing the job to the Windows spooler. 
Completed: wait until the spooler job has finished. Can be overridden per printer.
    
    
      
dryRunFolder
      
null
      
Absolute local or UNC path. When set, PDFs are written there instead of printed and not confirmed. Empty = print normally.
    
  
printerDefaults and printers
printerDefaults applies to every printer. An entry in 
printers overrides single values for one queue name; a value missing there (or 
null) falls back to the default. Details and advice in Printers and printing.
  
    
      
Key
      
Default
      
Description
    
  
  
    
      
queueName
      
only in 
printers, required
      
Printer name as the print task carries it (
printerName of the VeloxFactory printer). Unique, case-insensitive.
    
    
      
localName
      
only in 
printers
      
Alias: Windows printer that receives the jobs of this queue name. Empty = same name.
    
    
      
scaling
      
ActualSize
      
ActualSize (1:1 from the paper corner) or 
FitToPage (scaled into the printable area, centred)
    
    
      
autoRotate
      
true
      
Rotates a page when its orientation differs from the paper
    
    
      
dpi
      
null (72 to 1200)
      
Output resolution of the driver. Takes effect only if the driver offers exactly this resolution, otherwise the driver default stays. Empty = driver default.
    
    
      
copiesMode
      
Driver
      
Driver: one spooler job with n copies. 
Loop: one job per copy, for drivers that ignore the copy count (e.g. PDF24, Microsoft Print to PDF).
    
    
      
paperSource
      
null
      
Tray by name as the driver lists it. Unknown names keep the default tray.
    
    
      
duplex
      
Default
      
Default, 
Simplex, 
Vertical, 
Horizontal
    
    
      
color
      
Default
      
Default, 
Color, 
Monochrome (only on printers that support colour)
    
    
      
confirmation
      
only in 
printers
      
Overrides 
processing.confirmation for this printer
    
  
logging, statistics, health, ui
  
    
      
Key
      
Default
      
Description
    
  
  
    
      
logging.minimumLevel
      
Information
      
Verbose, 
Debug, 
Information, 
Warning, 
Error, 
Fatal. 
Debug shows WebSocket protocol details (ping, pong, auth). Applies immediately.
    
    
      
logging.retentionDays
      
30 (1 to 3650)
      
Log files older than this are deleted. Takes effect after a restart.
    
    
      
logging.maxFileSizeMb
      
250 (1 to 10240)
      
Size limit per log file; a day beyond it continues in 
_001, 
_002. Takes effect after a restart.
    
    
      
logging.eventLog
      
true
      
Warnings and errors to the Windows event log (needs the event source, created with the scheduled task). Takes effect after a restart.
    
    
      
logging.jsonFile
      
false
      
Additional log in compact JSON (
veloxprint-*.json) for log collectors. Takes effect after a restart.
    
    
      
statistics.retentionDays
      
365 (30 to 3650)
      
How long statistics are kept
    
    
      
statistics.resetAt
      
null
      
Set by Reset statistics. Jobs before this time no longer count.
    
    
      
health.enabled, 
health.port
      
false, 8765 (1024 to 65535)
      
Local health endpoint 
http://localhost:{port}/health, see Monitoring and troubleshooting
    
    
      
ui.errorNotifications
      
true
      
Windows notification of the tray icon on print errors
    
    
      
ui.windowWidth, 
windowHeight, 
windowMaximized
      
null, null, false
      
Last window size, written by the window itself

Receiving and processing print tasks
This page follows a print task through the Print Service: how it arrives, which instance takes it, how it is printed, retried and confirmed, and what protects it against being printed twice.
Receive modes
  
    
      
Mode
      
Behaviour
      
Use it when
    
  
  
    
      
Hybrid (default)
      
WebSocket events, plus a safety poll every 
safetyPollIntervalSeconds (120 s). While the WebSocket is down it polls every 
pollingIntervalSeconds (30 s) until the reconnect succeeds.
      
Always, unless there is a reason for another mode
    
    
      
WebSocket
      
Only events. Polls once at start and after every successful (re)subscribe, never periodically.
      
Minimal API load
    
    
      
Polling
      
Polls every 
pollingIntervalSeconds, no WebSocket
      
Reverb is not reachable from the printer machine (firewall, proxy)
    
  
Why the safety poll
Reverb delivers an event once and does not keep it. An event sent during a short network interruption is lost, and a connection can look alive without delivering events. The safety poll finds such tasks at the latest after its interval. Tasks the journal already knows are skipped, so polling never prints twice.
The poll request
GET /api/v1/report-print-task?status=pending&perPage=10&page=1&withMedia=true
    &withRelations=false&withAudit=true&broadcastId=Standard,Warehouse&withoutBroadcastId=false
The filter runs on the server: only tasks of the own broadcast ids are returned.
withMedia=true delivers the PDFs directly, no second request per task.
withAudit=true delivers the creation time for the lead time statistics.
If more pages exist, the next page is requested immediately instead of after the interval.
The WebSocket connection
Pusher protocol 7 against Laravel Reverb, private channel 
private-report-print-tasks, authorized with 
POST /api/v1/broadcasting/auth and the API token.
The event 
report-print-task.created carries 
{ model, id, broadcastId }. If the broadcast id matches, the service loads the task with 
GET /api/v1/report-print-task/{id}?withMedia=true.
Keep-alive: every 
pusher:ping of the server is answered with 
pusher:pong. After 25 s without traffic the service sends its own ping and drops the connection if no pong arrives within 30 s.
Reconnect with exponential backoff from 1 s to 60 s, ±20 % jitter. After every successful subscribe a catch-up poll fetches what was created in the meantime.
A first connection failure is logged as warning. An outage longer than 5 minutes writes event id 3000.
Broadcast ids: which instance prints what
Every print task and every printer in VeloxFactory can carry a broadcast id, usually one per site or printer group. An instance only takes tasks whose broadcast id is in its 
receive.broadcastIds, both from events and from polls.
Tasks without broadcast id are taken only with 
includeWithoutBroadcastId. VeloxFactory sends no WebSocket event for them, so they arrive only by polling: in Hybrid within 
safetyPollIntervalSeconds, in mode WebSocket only at start and after a reconnect. Give print tasks a broadcast id whenever they should print immediately.
⚠️ One instance per broadcast id. The job journal protects against double printing within one instance only. Two instances listening to the same broadcast id, or two instances with 
includeWithoutBroadcastId, print the same task twice.
Rate limit
The VeloxFactory API limits requests per IP address, by default 10 per minute (
API_RATE_LIMIT_PER_MINUTE). The service reads the limit from 
X-RateLimit-Limit and the rest from 
X-RateLimit-Remaining in every response and shows both on the dashboard.
  
    
      
Action
      
API calls
    
  
  
    
Task received by WebSocket
2 (GET task, set-printed)
    
Task received by poll
1 (set-printed) plus its share of the poll
    
Poll
1 per page
    
Error report
1 (set-status)
    
WebSocket login
1 (broadcasting/auth)
  
On HTTP 429 every API call of the process waits until 
Retry-After (60 s if the header is missing), then the same request is sent again. Print tasks wait, they do not fail. The API state shows Rate limited, event id 2002 is written.
The service does not slow down in advance. A low remaining count is only displayed.
Settings → Receiving shows the base load of the chosen mode in calls per minute (Hybrid with 120 s: 0.5) and warns when it exceeds half of the limit.
The limit counts per IP. All print services, scripts and MCP clients behind the same NAT share it. For print environments raise 
API_RATE_LIMIT_PER_MINUTE in the 
.env of your VeloxFactory instance.
Processing
Receiver -> queue -> journal check -> worker (max. maxParallelJobs) -> printer lock -> queue check -> print -> outbox
Journal check. A task the journal knows in state Printing or later is skipped. A task that was confirmed or reported before and is pending again (reprint) is loaded fresh; only if VeloxFactory really shows it as pending is it printed again.
Fetch. Tasks from a WebSocket event are loaded now, tasks from a poll already carry their PDF. A task that no longer exists or is no longer pending is dropped.
Printer. The queue name of the task is resolved to the local printer (alias, see Printers and printing). The Windows default printer is never used; a task without printer name fails with 
PrinterNotFound.
Printer lock. With 
serializePerPrinter only one job runs per printer, ordered by task id. Jobs for different printers run in parallel up to 
maxParallelJobs.
Queue check. Before printing, the Windows queue is checked. Not installed fails immediately. Offline, paper problem or error goes into retry without printing.
Print. See Printers and printing. The spooler document name is 
VF #{id} {file name}, so the job can be found in the Windows print queue.
Confirm. With 
confirmation = Spooled the task is confirmed as soon as the spooler accepted it. With 
Completed the service waits until the spooler job has finished (at most 
printTimeoutSeconds).
Retries
  
    
      
Retried (transient)
      
Fails immediately (permanent)
    
  
  
    
      
Printer reports offline, paper problem or error (
PrinterOffline)
      
Printer not installed for the service account (
PrinterNotFound)
    
    
      
Spooler refused to accept the job (
SpoolerError)
      
PDF missing, unreadable or not renderable (
RenderFailed)
    
    
      
      
Print call or spooler job ran into the timeout, spooler job ended with an error (
Timeout, 
SpoolerError)
    
  
With the defaults (
retryCount 3, 
retryBackoffSeconds [5, 30, 120]) a task waits about 2.5 minutes before it is reported as failed. For label printers that are offline longer, for example during a roll change, use more retries or a longer last value, e.g. 
[5, 30, 120, 300, 600] with 
retryCount 5.
ℹ️ Once handed to the spooler, a job is never retried. A failure after that point (timeout, spooler error) is only reported. Retrying could print the document twice.
Error reports
Permanent failures are reported with 
PATCH /api/v1/report-print-task/{id}/set-status, status 
error and an 
errorMessage of the form 
[Category] message, shortened to 1,000 characters. Categories: 
PrinterNotFound, 
PrinterOffline, 
RenderFailed, 
Timeout, 
SpoolerError, 
Unknown. The task shows the message in VeloxFactory.
Job journal and outbox
VeloxFactory has no endpoint to claim a task. The local journal in 
state.db takes that role and records every task with its state:
  
    
      
State
      
Shown as
      
Meaning
    
  
  
    
Received
Received
Taken, waiting or in retry
    
Printing
Printing
Print call running
    
Spooled
Spooled, not confirmed
In the spooler, confirmation pending. Never printed again.
    
Confirmed
Printed
VeloxFactory shows the task as printed
    
Failed
Failed
Failed, error report pending
    
ErrorReported
Error reported
VeloxFactory shows the task as error
    
Unknown
Unknown
The service ended while printing. Not printed again automatically, reported as error with Print state unknown after service restart, check printer and reset task if needed.
    
DryRun
Dry run
Written to the dry-run folder, not confirmed
  
Outbox. Confirmations and error reports are written to the outbox first and then sent. If the API is unreachable, the outbox retries with backoff (5 s, doubling, at most every 5 minutes) until it succeeds. If VeloxFactory answers 404 (task deleted) or 422 (rejected), the entry is dropped. After a crash, spooled tasks without outbox entry get their confirmation again. The dashboard tile Queue shows open outbox entries as to confirm.
Reprint. To print a task again, use Jobs → Print again in the window. It resets the task to pending in VeloxFactory (
PATCH set-printed with 
false), the next poll prints it. Resetting the task in VeloxFactory itself has the same effect.
Pause processing
A pause stops printing without stopping the service. Use it for printer maintenance, a roll change or while wrong tasks are cleaned up in VeloxFactory.
Set it on the dashboard (Pause / Resume) or under Settings → Processing with reason and optional end time. The pause is stored in 
config.json, so it survives a restart and a pause set in the window also pauses the headless engine.
While paused: the WebSocket stays connected, events are noted but not processed, periodic polls are skipped. Tasks already in the pipeline wait before their next print attempt; the waiting time does not count as a retry. A print call already in progress is not interrupted. The outbox keeps delivering confirmations.
New tasks stay pending in VeloxFactory.
On resume the service polls immediately and prints everything that arrived meanwhile.
The engine state is Paused with reason and end time. The health endpoint still answers 200.
Dry run
For tests and demonstrations without paper. With 
processing.dryRunFolder set (or 
--dry-run <folder> on the command line, which applies to that run only) every task is received, fetched and resolved as usual, but instead of printing the PDF is written to 
<folder>\<task id>_<file name>. Nothing is confirmed, the task stays pending in VeloxFactory.
⚠️ Dry-run tasks are not printed later. The journal marks them as Dry run, and this instance skips them after the dry run is switched off, although they are still pending in VeloxFactory. Use a test broadcast id for dry runs, or create new print tasks afterwards.

Printers and printing
A print task names its printer by the 
printerName of the VeloxFactory printer master data (see Printers: master data for your print targets). The Print Service calls this the queue name and maps it to a Windows printer on its machine. This page covers that mapping, the per-printer settings, how pages are printed and which printers are not suitable.
Installing printers for the service
The headless service runs under its own account without a desktop. What that account cannot see, it cannot print on.
  
    
      
Installation
      
Shown as
      
Suitable
    
  
  
    
      
Local printer (USB, TCP/IP port)
      
Local
      
Yes
    
    
      
Print server connection installed for all users
      
Machine-wide
      
Yes
    
    
      
Print server connection added by a user (
\\server\printer)
      
User profile only
      
No. Only that user sees it, the service account does not.
    
  
Install a print server connection machine-wide (as administrator, takes effect after the spooler restarts or the next logon):
rundll32 printui.dll,PrintUIEntry /ga /n\\printsrv01\WH-LABEL-01
Restart-Service Spooler
ℹ️ The default printer is never used. The default printer is a per-user setting. The service always prints on the printer named in the task (or its alias). A task without printer name fails with 
PrinterNotFound.
The printer list
The Printers page of the window compares four sources:
the VeloxFactory printer master data (
GET /api/v1/printer, needs 
printer:read), filtered on the own broadcast ids. Printers without broadcast id only appear with 
includeWithoutBroadcastId,
the printers installed on this machine,
printers with own settings in 
config.json,
printers that received jobs in the last 7 days but are in none of the sources above (Only in recent print jobs).
Local printers that no row points to are listed at the end as Not in VeloxFactory, useful as alias targets and for test pages.
  
    
      
Column
      
Content
    
  
  
    
Printer
Display name from VeloxFactory and queue name; an alias shows as 
→ local name
    
Type, Location
From VeloxFactory
    
Local
Local, Machine-wide, User profile only, Installed (scope unknown) or Missing
    
Status
Windows queue: Ready, Offline, Paper problem, Error, Paused, Unknown, plus the number of jobs in the queue
    
Hint
Not installed on this machine, Only connected for this user profile, Prints with a dialog, not suitable headless, Inactive in VeloxFactory, tasks are printed nevertheless
  
Actions per row: copy the printer name, print a test page, edit the printer settings, open the Windows print queue.
⚠️ A printer shows as "Not in VeloxFactory" although it exists there? Its broadcast id is not one of this instance's broadcast ids, or it has none and 
includeWithoutBroadcastId is off. Set the broadcast id of the printer in VeloxFactory, or turn on Also take tasks without broadcast id under Settings → Receiving, which also takes all print tasks without broadcast id.
Alias: local printer name
The alias (
localName) sends the jobs of a queue name to a Windows printer with a different name. VeloxFactory does not need to know about it.
"printers": [
  { "queueName": "WH-LABEL-01", "localName": "\\\\printsrv01\\WH-LABEL-01" },
  { "queueName": "OFFICE-A4",   "localName": "Brother HL-L3210CW series Printer" }
]
Without alias the Windows printer must have exactly the queue name (case-insensitive).
Typical uses: the same printer has a different name on every workstation, a temporary replacement printer, or a PDF printer for tests.
The alias is set in the printer editor, field Local name. The same name as the queue name, or empty, stores no alias.
The alias lives in the local 
config.json. Every machine needs its own entry.
Printer settings
printerDefaults in Settings → Printer defaults applies to all printers. The printer editor on the Printers page overrides single values for one printer (Use default keeps the default). The effective value is: printer override, else default, else the driver's setting.
  
    
      
Setting
      
Effect
    
  
  
    
Scaling
Actual size: 1:1, placed at the physical paper corner (labels, forms). Fit to page: scaled into the printable area and centred.
    
Auto rotate
Switches to landscape for a page only when page and paper orientation differ. Label papers are often defined landscape already.
    
DPI
Selects this output resolution of the driver if the driver offers exactly it; otherwise the driver default stays. For label printers use the resolution of the print head (203 or 300).
    
Copies
One job, copies by the driver or One job per copy. Use the second for drivers that ignore the copy count. PDF24 and Microsoft Print to PDF report copy support but produce only one copy.
    
Paper source
Tray by name, the editor lists the trays of the driver
    
Duplex
Driver default, simplex, long edge (vertical), short edge (horizontal)
    
Color
Driver default, colour, monochrome
    
Confirmation
Not a driver setting: when the task is confirmed to VeloxFactory, after spooling or after the spooler job completed
  
All settings apply to the single print job only. The service never changes the configuration of the Windows printer. Some drivers ignore job settings for duplex, colour or tray and use their own defaults; in that case change the setting in the printing preferences of the Windows printer.
How pages are printed
The PDF stays in memory, nothing is written to disk.
PDFium (the PDF engine of Chromium) draws every page directly onto the device context of the printer, in the device resolution and without an intermediate bitmap. Text, lines and barcodes are sent as vector graphics and print as sharp as the printer can.
The target rectangle is computed per page from the printer's resolution and printable area, so pages of different size or orientation in one document work.
Output uses the Windows spooler without any print dialog. The document name in the spooler is 
VF #{task id} {file name}.
PDFium is not thread-safe; its calls are serialised inside the service, jobs on different printers still run in parallel.
Limitations:
Pages with transparency (for example PNG images with alpha channel) are output by PDFium as an image in device resolution.
Form fields (AcroForm) are not printed.
Lines with width 0 in the PDF are drawn as the thinnest line the device can print, one printer dot. On high-resolution printers they become very thin. Give lines and borders in the JRXML an explicit width, e.g. 
lineWidth="0.5".
Printers that open a dialog
Some printers ask for a file name or open an application window when printing. In the headless service there is no desktop: the dialog is invisible and waits forever. The job ends after 
printTimeoutSeconds and is reported as 
Timeout.
The service marks these printers with Prints with a dialog, not suitable headless. Detected by port (
PORTPROMPT:, 
XPSPort:, 
PDF24:, 
FAX:, 
SHRFAX:) or driver name (Microsoft Print To PDF, Microsoft XPS Document Writer, OneNote, PDF24, Fax). In the window they work, the test page asks for confirmation first. For PDF tests without dialog use the dry run or configure PDF24 with automatic saving.
Test page
The test page is an A4 PDF in the VeloxFactory design, generated locally without API access. It contains instance name, printer, time and account, a line pair pattern that shows the effective resolution, grey scale steps, a Code 39 barcode and a frame 10 mm from the paper edge to check margins and scaling. It is printed with the settings of the printer, including alias.
Print it from the Printers page or on the command line:
& "C:\kiwisoftware\VeloxPrint\app\bin\kiwisoftware.VeloxFactory.PrintService.App.exe" --test-print WH-LABEL-01
ℹ️ Test under the right account. A test page from the window runs under your account, the headless service under the service account. A printer connected only for your profile prints the test page but fails in production. Check the column Local: it must say Local or Machine-wide.

The Print Service window
Started without parameters, the Print Service opens its window in the VeloxFactory design (light, dark or system theme). The header shows the pages, the instance name and the mode badge: Interactive when the engine runs inside the window, Monitor when a headless engine runs and the window only shows its state. Screenshots follow.
Dashboard
  
    
      
Tile
      
Content
    
  
  
    
Engine
Running, paused (with reason and end), stopped; mode, account, uptime; Pause and Resume
    
API
OK, token rejected (401/403), rate limited (429), unreachable; time of the last successful request
    
WebSocket
Subscribed, reconnecting (attempt n), off; reconnects today
    
Rate limit
Remaining of limit from the response headers, as bar
    
Queue
Active, waiting, in retry, to confirm (outbox)
    
Printers
Number of printers OK and with problem, including their names; tooltip with the state per printer, click opens the Printers page. Checked are printers with own settings and printers of jobs from the last 7 days. A problem is any queue state other than Ready.
  
Below the tiles: the last 20 jobs and the last 5 errors. A click opens the job.
Console
The live log, written for users: Task #4711 received (WebSocket, Standard) → WH-LABEL-01, 2 copies instead of raw protocol events.
Columns: time, level (icon and colour), area (API, WS, Print, Engine), task, message.
Filters: levels as chips, area, text search, a single task, errors only. Clear filters resets them.
Autoscroll can be paused. Copy a line, export the selection or all visible lines, click a task to open it.
Protocol details (ping, pong, channel auth) are logged on level Debug and hidden by default.
Buffer: 10,000 lines in the window. In monitor mode the lines come from 
state.db, which keeps the last 50,000 entries.
Jobs
The local history from the job journal: id, time, printer, file, copies, pages, channel (WebSocket or poll), duration, status, trace id. Filters for period, status and printer, search by 
#id, file name, trace id or error text.
The detail view shows the timeline of states, error text and attempts. Actions:
  
    
Open in VeloxFactory
Opens 
{baseUrl}/report-print-task/{id}/show in the browser
    
Print again
Sets the task back to pending in VeloxFactory (after confirmation); the next poll prints it
    
Send confirmation again
Sends an open outbox entry now. In monitor mode the headless engine repeats open confirmations automatically.
    
Copy
Printer name (with alias: the local printer) and trace id. The trace id links the job to the history record and print task in VeloxFactory.
  
Printers
Comparison of VeloxFactory printers, local printers, own settings and printers of recent jobs, with state, hints, test page, printer editor and a link to the Windows print queue. Described in Printers and printing.
Statistics
Local statistics of this instance, nothing is sent to VeloxFactory.
Tiles for today and 7 days: jobs printed and failed, error rate, pages.
Jobs over time per hour (24 h, 7 days, 30 days), pages and copies per printer, top error categories.
Lead time from creation in VeloxFactory to confirmation (median, P95), share of WebSocket and poll, WebSocket availability and reconnects, API calls and 429 events.
Export as CSV. The mouse wheel over a chart zooms the chart only.
Retention 
statistics.retentionDays (365 days); after 30 days the data is kept as daily aggregates.
Settings
  
    
      
Group
      
Content
    
  
  
    
Connection
Base URL, API token, allow unencrypted, timeout, server time zone, Test connection
    
WebSocket (Reverb)
Scheme, host, port, app key, channel
    
Receiving
Mode, broadcast ids as chips, tasks without broadcast id, intervals, page size, API base load compared with the rate limit
    
Processing
Pause with reason and end time, parallel jobs, one job per printer, retries, timeout, confirmation, dry-run folder
    
Printer defaults
Defaults for all printers
    
Logging and statistics
Log level, retention, file size, event log, JSON file, statistics retention. Maintenance: Reset statistics and Clear logs (administrator rights)
    
Operation
Scheduled task: set up, start, remove, state and XML. Local health endpoint. Error notifications.
    
Import and export
Configuration as file, never with token
  
Save writes 
config.json, the engine applies it without restart. Unsaved changes are asked for when leaving the page.
Test connection checks: reachability, token (
GET /report-print-task?perPage=1), printer master data (
printer:read), channel authorization and WebSocket handshake (15 s), rate limit headers compared with the base load.
Reset statistics counts from now on. The job journal stays, it protects against double printing.
Clear logs empties the console history and deletes all log files of the instance except today's.
Without write access to the data folder the window offers Restart as administrator.
Info
Version, .NET runtime, Windows account (with Administrator when elevated), mode, instance id, paths of configuration, data and log folder with buttons to open them, and Create support package (see Monitoring and troubleshooting).
Notification area
In interactive and monitor mode the Print Service has a tray icon with status colour (green OK, yellow warning, red error) and a menu: open, pause, exit. Closing the window hides it in the notification area; in interactive mode the engine keeps running. Exit stops the engine gracefully: running jobs finish, the outbox is flushed. Print errors show a Windows notification unless 
ui.errorNotifications is off.

Command line reference
The program file is 
kiwisoftware.VeloxFactory.PrintService.App.exe in 
app\bin. Without parameters it opens the window. All other functions are available as parameters, for the scheduled task, scripts and software distribution.
Parameters
  
    
      
Parameter
      
Effect
      
Exit codes
    
  
  
    
      
(none)
      
Window, interactive or monitor mode
      
0
    
    
      
--headless
      
Engine without window, for the scheduled task. Never creates a window or dialog.
      
0, 1, 2, 3, 10
    
    
      
--config <path>
      
Alternative configuration file, for several instances per machine. Combines with every other parameter.
      
    
    
      
--console
      
Attaches a console window and writes the log to it as well. For debugging an interactive start.
      
    
    
      
--validate-config
      
Validates the configuration and runs the connection test (reachability, token, rate limit, printer master data, WebSocket). Prints one line per step.
      
0, 1
    
    
      
--install-task --user <account>
      
Sets up the scheduled task (see Installation and updates). Asks for the password. Administrator rights required.
      
0, 4
    
    
      
--uninstall-task
      
Removes the scheduled task of the instance. Administrator rights required.
      
0, 4
    
    
      
--test-print <printer>
      
Prints the test page on the printer, locally without API. Uses the printer settings and alias of the configuration.
      
0, 5
    
    
      
--dry-run <folder>
      
Starts the engine headless and writes PDFs into the folder instead of printing, nothing is confirmed. Applies to this run only, the configuration is not changed.
      
like 
--headless
    
    
      
--support-package <target.zip>
      
Writes the diagnostic package (see Monitoring and troubleshooting). Works while the engine runs.
      
0
    
    
      
--stop
      
Ends engine and windows of the instance gracefully: running print jobs finish, the outbox is flushed. Waits until the engine has ended. Administrator rights required. Used by 
update.ps1.
      
0, 6
    
    
      
--help, 
-h, 
/?
      
Shows the usage
      
0
    
  
Paths (
--config, 
--dry-run, 
--support-package) must be absolute. The Task Scheduler starts in 
C:\Windows\System32, a relative path would end up there.
Mapped network drives do not exist for the service account. Use local paths or UNC paths.
An unknown parameter or a missing value prints the usage and ends with exit code 1.
Exit codes
  
    
      
Code
      
Meaning
    
  
  
    
0
OK, or regular stop of the engine
    
1
Configuration invalid, connection test failed, or invalid parameters
    
2
The engine of this instance is already running
    
3
API token rejected at start
    
4
Scheduled task could not be set up or removed (rights, account, password)
    
5
Test print failed
    
6
Stop failed: no administrator rights or the engine did not end in time
    
10
Unexpected error
  
Exit codes 1 and 3 of a headless start are visible in the Task Scheduler as Last run result. The Task Scheduler restarts the task every minute; fix the configuration or token, the next start picks it up.
Examples
$exe = "C:\kiwisoftware\VeloxPrint\app\bin\kiwisoftware.VeloxFactory.PrintService.App.exe"
# check configuration and connection
& $exe --validate-config
#   Configuration: C:\kiwisoftware\VeloxPrint\data\config.json
#   [OK]      Configuration is valid
#   [OK      ] Reachability: https://vf.example.com
#   [OK      ] Token: Token accepted, report-print-task:read granted.
#   [OK      ] WebSocket: Subscribed to private-report-print-tasks on vf.example.com:443.
# scheduled task for the default instance and for a second instance
& $exe --install-task --user .\svc-veloxprint
& $exe --config C:\kiwisoftware\VeloxPrint\data\lager-nord.json --install-task --user .\svc-veloxprint
# test page
& $exe --test-print WH-LABEL-01
# engine in a console window for debugging (stop the scheduled task first)
& $exe --headless --console
# dry run into a folder
& $exe --dry-run C:\Temp\veloxprint-dryrun --console
# diagnostic package
& $exe --support-package C:\Temp\veloxprint-support.zip
# graceful stop of the default instance
& $exe --stop
ℹ️ Exit code in PowerShell. The program is a Windows application, PowerShell does not wait for it with the 
& operator. To read the exit code, use 
$p = Start-Process -FilePath $exe -ArgumentList '--validate-config' -Wait -NoNewWindow -PassThru; $p.ExitCode.

Monitoring and troubleshooting
The headless service has no window, so it reports through log files, the Windows event log and an optional local health endpoint. For support cases it bundles everything into one diagnostic package.
Log files
data\logs\veloxprint-20260925.log
data\logs\veloxprint-20260925_001.log        same day, after the size limit
data\logs\veloxprint-20260925.json           optional, logging.jsonFile
data\logs\lager-nord\veloxprint-...          instance with --config lager-nord.json
2026-09-25 07:16:48.120 +02:00 [INF] [Print] [#35] Task #35 received (WebSocket, Standard) -> WH-LABEL-01, 1 copy
2026-09-25 07:16:49.402 +02:00 [INF] [Print] [#35] Task #35 spooled to WH-LABEL-01, 1 page
2026-09-25 07:16:49.655 +02:00 [INF] [API] Task #35 confirmed as printed
Format: time with offset, level (
VRB, 
DBG, 
INF, 
WRN, 
ERR, 
FTL), area (
API, 
WS, 
Print, 
Engine), task id where known, message.
One file per day, a new file (
_001, 
_002) when 
logging.maxFileSizeMb (250 MB) is reached.
Files older than 
logging.retentionDays (30) are deleted, by age, not by count.
Lines of a task carry its task id and trace id; the trace id links it to the history record and print task in VeloxFactory.
The API token never appears in any log.
Windows event log
Warnings and errors go to the event log Application, source VeloxFactory Print Service, with fixed event ids for monitoring systems such as Checkmk, PRTG, Zabbix or SCOM. The source is registered when the scheduled task is set up; without it the event log output stays off. Switch it off with 
logging.eventLog.
  
    
      
Event id
      
Meaning
      
Action
    
  
  
    
1000
Engine started
    
1001
Engine stopped
Unexpected outside updates and reboots
    
2000
API not reachable
Network, DNS, proxy, VeloxFactory up?
    
2001
API token rejected (401/403)
Token revoked or rights missing, enter a new token
    
2002
Rate limit reached (429)
Occasionally harmless. Often: raise 
API_RATE_LIMIT_PER_MINUTE or the poll intervals
    
3000
WebSocket down longer than 5 minutes
Reverb, firewall, host, port, app key. Hybrid keeps printing by polling.
    
4000
Print failed
Error text contains the category
    
4001
Printer missing
Install machine-wide or set an alias
    
5000
Configuration invalid
A changed configuration was not applied, the engine keeps the last valid one
  
Local health endpoint
Optional, switched on under Settings → Operation (
health.enabled, port 
health.port, default 8765). It listens only on 
127.0.0.1, needs no URL reservation and no administrator rights, and is not reachable from other machines. A monitoring agent on the same machine polls it.
GET http://localhost:8765/health
{
  "status": "ok",
  "engine": "Running",
  "hostMode": "Headless",
  "version": "2.0.1",
  "startedAt": "2026-09-25T05:01:12+00:00",
  "api": {
    "state": "Ok",
    "lastApiSuccess": "2026-09-25T07:16:49+00:00",
    "lastApiError": null,
    "rateLimit": { "limit": 60, "remaining": 58, "rateLimitedUntil": null }
  },
  "websocket": { "state": "Subscribed", "since": "2026-09-25T05:01:14+00:00", "reconnectAttempt": 0 },
  "queue": { "active": 0, "waiting": 0, "retrying": 0, "outbox": 0 },
  "printers": { "ok": 3, "withProblems": 0 }
}
  
    
      
HTTP status
      
Condition
    
  
  
    
200, 
"status": "ok"
Engine running or paused, and API state OK, unknown or rate limited
    
503, 
"status": "degraded"
Everything else, e.g. token rejected or API unreachable
    
no answer
Engine not running
  
Worth alerting on besides the status: 
queue.outbox above 0 for a longer time (printed but not confirmed), 
queue.retrying above 0 (printer problem), 
printers.withProblems above 0, 
websocket.state not 
Subscribed.
Diagnostic package
Info → Create support package, or 
--support-package C:\Temp\support.zip. The ZIP contains:
  
    
versions.txt
Program version, machine, account, Windows, .NET, configuration path, whether a token is stored
    
config.json
Configuration, anything resembling a token removed
    
engine-status.json
Last engine status (as in the health endpoint)
    
printers.txt
Local printers with scope, queue state, jobs, driver and driver version, port, dialog flag
    
journal-last-500.csv
The last 500 jobs of the journal
    
outbox.csv
Open confirmations and error reports: 
task id;kind;attempts;next attempt;last error. Empty is the normal case.
    
config-changes.csv
Last 500 configuration changes: time, account, changed keys
    
scheduled-task.txt
XML definition of the scheduled task
    
logs/
The 7 newest log files
  
The API token is removed from every file.
Common problems
  
    
      
Symptom
      
Cause and fix
    
  
  
    
      
Tasks stay pending, nothing in the log
      
Broadcast id of the task is not in 
receive.broadcastIds, or the task has none and 
includeWithoutBroadcastId is off. Processing paused? Engine running (dashboard, Task Scheduler)?
    
    
      
Tasks are printed, but only after a minute or two
      
Tasks without broadcast id: VeloxFactory sends no event for them, only the poll finds them. Give them a broadcast id. Otherwise the WebSocket is not subscribed: check the WebSocket tile and Test connection (host, port, scheme, app key, firewall). A token without 
report-print-task:read fails at the channel authorization.
    
    
      
Prints from the window, fails from the scheduled task with 
PrinterNotFound
      
Printer only connected for your user profile. Install it machine-wide (Printers and printing).
    
    
      
Network printer fails from the scheduled task
      
Task set up without stored password, or a local account against a domain print server. Use a domain account and set up the task again.
    
    
      
Error 
[Timeout] after 120 s
      
Printer opens a dialog (PDF printers, OneNote, fax), or the driver hangs. Check the hint on the Printers page.
    
    
      
Only one copy instead of n
      
Driver ignores the copy count. Set Copies to One job per copy for this printer.
    
    
      
Output shifted, cut off or too small
      
Check scaling (Actual size for labels), paper size of the driver and auto rotate. The frame of the test page shows margins and scaling.
    
    
      
Very thin or missing lines
      
Lines with width 0 in the report. Set 
lineWidth in the JRXML.
    
    
      
Printed, but pending in VeloxFactory
      
Confirmation in the outbox (Queue tile to confirm, 
outbox.csv). The column last error names the reason. The task is not printed again, the confirmation follows as soon as the API answers.
    
    
      
Task shows error Print state unknown after service restart
      
The service ended while the task was printing. Check the printer; if nothing came out, use Print again.
    
    
      
Many 429 / event 2002
      
Several services or scripts behind one IP share the limit. Raise 
API_RATE_LIMIT_PER_MINUTE, use Hybrid instead of short polling intervals.
    
    
      
Scheduled task shows result 0x1 / 0x3
      
Exit code 1 configuration invalid, 3 token rejected. Start the window or 
--validate-config.
    
    
      
Window cannot save settings
      
No write access to the data folder. Use Restart as administrator.
    
    
      
update.ps1 refuses to update
      
Local changes in 
app\, or a window of the Print Service is still open under another user. Close it and run the update again.

Mail your renderings
Sending rendered reports by mail: the mailing segment, mailers, mail templates and the mail queue.

Report Mailing: sending renderings by mail
A rendered report usually has somewhere to go: back to the caller as Base64 or as a URL, straight into a print task, or into the mailbox of whoever needs the document. Report Mailing is that last destination. A render request carries an optional 
mailing segment, and once the render succeeded VeloxFactory sends an HTML mail through a configured mailer, using a configured template, with the PDF attached and, if you want it, an xlsx export of the same data.
Mailing is an addition to a render, never a condition of it. A request without a 
mailing segment is a plain render, and a mail that fails never turns a successful render into an error.
Screenshot placeholder: 
mailing.history-record-modal.png
The mail dialog of a Report History Record with mailer, template, recipients, attachments and the background switch.
The three parts
Mailing is built from three things you configure once and one thing you send per render.
  
    
      
Part
      
What it holds
    
  
  
    
      
Mailer
      
The SMTP account: host, port, credentials, sender address, and the dispatch rate limits your provider allows. Master data under Configuration.
    
    
      
Mail Template
      
Subject and body, written in a WYSIWYG editor, with placeholders and optional whitelabeling. Master data under Configuration.
    
    
      
Mailing segment
      
Per request: which mailer, which template, who receives it, what is attached, and whether it goes out immediately or through the queue.
    
    
      
Report Mail Task
      
The record of one send attempt: recipients, the rendered subject and body, the attachments, the status and, if something went wrong, the error.
    
  
Mailing from a render request
The 
mailing segment is optional and sits next to the fields you already know:
{
    "outputType": "base64",
    "parameters": { "P_ORDER_NO": "4711" },
    "createPrintTask": false,
    "createHistoryRecord": true,
    "mailing": {
        "mailer": "Office SMTP",
        "mailTemplate": "Report Delivery",
        "to": ["disposition@example.com", "[data.first.customerEmail]"],
        "cc": [],
        "bcc": ["archive@example.com"],
        "contactName": "[data.first.customerName]",
        "includePdf": true,
        "pdfFileName": "Order_[parameters.P_ORDER_NO]",
        "includeExcel": true,
        "includeParameters": true,
        "excelFileName": "Data_[traceId]",
        "sendAsync": false
    }
}
mailer and 
mailTemplate accept either the numeric ID or the unique name of the record, so a request stays readable. Only active records are resolved.
  
    
      
Field
      
Required
      
Description
    
  
  
    
      
mailer
      
yes
      
ID or unique name of an active Mailer.
    
    
      
mailTemplate
      
yes
      
ID or unique name of an active Mail Template.
    
    
      
to, cc, bcc
      
to: yes
      
Address lists. Literal addresses are validated before the render is spent, addresses containing a placeholder are resolved afterwards.
    
    
      
contactName
      
no
      
Free text for a personal greeting, available in the template as 
[contactName]. May itself be a placeholder.
    
    
      
includePdf
      
no
      
Default 
true. Set it to 
false for a notification mail that only carries the xlsx, or nothing at all.
    
    
      
pdfFileName
      
no
      
Base name the PDF carries as an attachment of the mail, without extension. The stored file keeps its own name, nothing is copied.
    
    
      
includeExcel
      
no
      
Default 
false. Builds an xlsx from the rows that were actually rendered.
    
    
      
includeParameters
      
no
      
Prints the parameters as a block above the data table in the xlsx.
    
    
      
excelFileName
      
no
      
Base name the xlsx carries as an attachment, same rules as 
pdfFileName.
    
    
      
sendAsync
      
no
      
Default 
false. 
true hands the mail to the queue and answers immediately.
    
  
ℹ️ A failed mail never fails the render. Whatever goes wrong with the mailing, the render response stays a success and the detail lands in 
meta.mailing and on the mail task. Your integration keeps its PDF.
The one combination that is refused up front is 
outputType: "preview" together with 
mailing: a preview render deletes its own file immediately, so there would be nothing to attach.
The Excel attachment
includeExcel turns the data of the render into a real xlsx, not a CSV with a different name. The rows come from what was actually rendered, which matters for reports fed by an SQL adapter: there the rows only exist in the render result, never in your request.
The sheet has a header row in the report's accent colour, frozen below the header, with an auto filter across the table. Columns are typed from the report's field definitions, so an integer is a number, a date is a real Excel date and a decimal keeps its format. For a dynamic array without field definitions the type is inferred from the values. Rows with differing keys are merged into one header, in first-seen order, and missing values stay empty.
With 
includeParameters the parameters are printed above the table, so the recipient can see what the report was asked for without opening the mail again.
If the render produced a history record, the xlsx is stored on it and stays downloadable from the history record page. It is cleaned up by the same retention as the PDF.
Placeholders in recipients and attachment names
Subject and body are placeholder-driven, and so are the recipients, the contact name and the attachment names. They all accept the same catalog, which is what makes mailing useful for data that only exists after the render.
Every route that takes recipients accepts them: the 
mailing segment of a render, 
POST /report-history-record/{id}/mail, 
POST /report-mail-task and the repeat endpoint. The failure recipients of a schedule are the exception, they are plain addresses, because a run that failed has no render to resolve against.
"to": ["[data.first.customerEmail]"],
"contactName": "[data.first.customerName]",
"pdfFileName": "Lieferschein_[parameters.P_ORDER_NO]_[now.date]"
For a report with an SQL adapter, 
[data.first.<column>] addresses the rows the query fetched. The recipient list is therefore a result of the render, not an input to it.
A few rules are worth knowing:
  
    
      
Situation
      
Behaviour
    
  
  
    
      
A placeholder holds several addresses
      
Comma or semicolon separated values are split, trimmed and de-duplicated. One column can address a whole distribution list.
    
    
      
A 
cc or 
bcc placeholder resolves to nothing
      
The address is left out and the mail goes anyway. A render reports it in 
meta.mailing.unresolvedPlaceholders, 
POST /report-mail-task as an Unresolved placeholder note in 
meta.messages.
    
    
      
No valid 
to address is left, or one resolves to something that is not an address
      
In a render no mail is sent, the reason is in 
meta.mailing.errors and the render itself is unaffected. On 
POST /report-mail-task the call answers 422 and no task is created.
    
    
      
What the mail task stores
      
The resolved address list, not the placeholder. 
[recipients.toCount] and the other counters in subject and body therefore count real recipients.
    
    
      
Column names
      
Matched exactly as the adapter returns them. 
[data.first.EMAIL] is not 
[data.first.email].
    
    
      
Attachment names
      
Resolved, then made file-system safe with case and underscores preserved. Umlauts are transliterated, invalid characters collapse to a single hyphen, the extension is forced.
    
  
ℹ️ Placeholder values are inserted as text. A resolved value that happens to contain markup, for example a customer name with a 
<b> in it, appears literally in the mail instead of changing its formatting. The markup you set in the editor is unaffected.
ℹ️ The name is a label, not a file. 
pdfFileName and 
excelFileName only change what the attachment is called in the mail. On disk the PDF and the xlsx are always stored under the trace id, they hang on the history record, stay downloadable from it and are deleted with it. Two mails may carry the same attachment name without anything being overwritten.
Without a requested name the attachment is called like the stored file, which is the trace id plus its extension.
Immediately or through the queue
By default the mail is sent while the request is still open. The response then already tells you whether it went out. That is the right mode for a single document and a fast relay.
sendAsync: true creates the mail task, hands it to the queue and answers immediately. The mail is sent by a Horizon worker, the task moves from Pending to Sent, and a failure is retried with backoff before it ends as Error. Use it for bulk runs and for slow or unreliable SMTP servers, where waiting for the transport would block the render.
⚠️ Asynchronous sending needs a running queue. Without 
php artisan horizon the mail task stays Pending forever. It is visible in the Mail Queue, so nothing is lost, but nothing is sent either.
There is a third case you do not ask for: if the mailer's rate limit is exhausted, a synchronous send is converted into a delayed queued send instead of failing. The mail is not lost, the response says so, and the task shows when it will go out. See the Mailers page for the windows.
Mailing from the frontend
The same settings are available in four places in the UI, built from one shared block of fields, so they look and behave identically everywhere.
  
    
      
Place
      
How it works
    
  
  
    
      
Generate PDF
      
A Send results via Mail toggle in the Output Settings. Configure it once, and every render from that page mails its result.
    
    
      
Scan2Print
      
The same toggle in the station configuration. Every scan then prints and mails.
    
    
      
Report History Record
      
A Send Mail button that mails a document which was rendered earlier, with a freely chosen mailer, template and recipients.
    
    
      
Job Scheduler
      
The same toggle on a render job. Every run of the schedule mails its result.
    
  
In the configuration modals the mailing settings live in the session alongside the rest of the output settings, and the values are kept even while the toggle is off, so switching mailing off for a moment loses nothing. The file name fields appear only while their attachment switch is on.
After a render the notification says what happened to the mail. A mail that did not go out as configured turns the success notification into a warning instead of hiding the problem.
The block is only rendered at all when the current user may create mail tasks and at least one active mailer and one active template exist. Nobody is offered a button that cannot work.
Screenshot placeholder: 
mailing.generate-pdf-settings.png
Output Settings of the Generate PDF page with the mailing block expanded.
On a schedule
A mail does not need a caller. A render job in the Job Scheduler carries the same mailing settings as a render request, so a schedule puts the shift report in a mailbox at six every morning without anybody asking for it.
Two things work differently from an interactive send. The schedule's owner and API token decide what may go out: the token needs 
report-mail-task:create, and a revoked token or a deactivated owner parks the schedule rather than mailing. And placeholders are resolved at the moment the run fires, so 
[now.date] in a subject line or an attachment name carries the date of that run, not the date the schedule was saved.
Every run is logged with its trace id. A mail task that ends in Error, or anything reported in 
meta.mailing, marks the run as a warning, so a schedule whose mail is not arriving is visible in the run log without opening the Mail Queue.
ℹ️ Two different mails. The mail configured here is the document itself. A schedule that could not be executed at all sends the Job Scheduler's own failure mail to its own recipients. See Schedule your jobs.
The Mail Queue
Every send attempt, synchronous or queued, is recorded as a Report Mail Task. The overview lives in the main menu under Mail Queue and is a regular VeloxFactory lookup with the usual filters and the usual session-persisted state.
A mail task keeps what was actually sent, not just what was requested: the resolved recipients, the rendered subject, the rendered body and the names of the attachments. The detail page shows the mail exactly as the recipient received it, rendered in an iframe from the stored HTML, whitelabeling included.
  
    
      
Status
      
Meaning
    
  
  
    
      
Pending
      
Queued, or waiting for a free rate limit slot. The task shows when it is due.
    
    
      
Sent
      
The transport accepted the message, with the timestamp. Delivery itself is not tracked.
    
    
      
Error
      
The send failed after its retries. The transport's own message is on the task.
    
  
Repeat resends a task. It opens a dialog in which mailer and recipients can be changed before sending, so a mail that went to the wrong address is corrected rather than cloned. Subject and body are re-rendered from the current template when the history record still exists, otherwise the stored snapshot is reused. The repeated task gets its own trace id, derived from the original.
The same table also appears on the Report History Record page, so the mails belonging to one document are visible where the document is.
Screenshot placeholder: 
mailing.mail-queue.png
Mail Queue overview with status badges, recipients and the repeat action.
Retention
Mail tasks are cleaned up by the Purge Job, the consolidated cleanup schedule of the Job Scheduler. It removes print tasks and mail tasks before the history records they reference, so nothing is deleted out from under a reference. How long mail tasks are kept is a retention on that schedule, editable in the frontend or through the API like everything else; an empty value switches the step off entirely.
The same work is available as a standalone command:
php artisan report-mail-tasks:purge --days=30
Attachments are not owned by the mail task. The PDF and the xlsx belong to the history record and are removed by its retention step, or, if no history record was created, by the orphaned-file step.
The API
Besides the 
mailing segment on 
POST /report-config/{id}/render, mailing has endpoints of its own.
  
    
      
Endpoint
      
Description
    
  
  
    
      
POST /report-history-record/{id}/mail
      
Mail a document that was rendered earlier. Takes the same fields as the mailing segment, including placeholders in recipients and attachment names. Builds the xlsx on the fly if the record does not have one yet.
    
    
      
GET /report-mail-task
      
List mail tasks, filterable by status.
    
    
      
GET /report-mail-task/{id}
      
A single mail task, with its relations and its audit segment on request.
    
    
      
POST /report-mail-task
      
Create and dispatch a mail task directly. 
to, 
cc and 
bcc take literal addresses or placeholders, resolved against the render of the referenced history record.
    
    
      
POST /report-mail-task/{id}/repeat
      
Resend a task. Optional 
mailer, 
to, 
cc and 
bcc override the original values, anything left out is reused. The overriding recipients accept placeholders too, resolved against the history record behind the task; if the task has none, only the generic placeholders such as 
[user.email] resolve.
    
    
      
DELETE /report-mail-task/{id}
      
Delete a mail task. The attachments belong to the history record and are not touched.
    
  
A render that mailed something returns the mail task in its response, and anything noteworthy about the mailing in 
meta.mailing:
  
    
      
Key
      
Meaning
    
  
  
    
      
errors
      
The mail was not sent, with the reason.
    
    
      
skipped
      
The render failed, so there was nothing to send.
    
    
      
excelError
      
The xlsx could not be built. The mail goes out with the PDF only.
    
    
      
unresolvedPlaceholders
      
Placeholders in recipients, contact name or attachment names that resolved to nothing.
    
  
AI assistants
The MCP server exposes mailing the same way it exposes printing: the 
mailing segment is part of the render tool, and mail tasks, mailers and templates have their own tools. Because mailer and template are resolved by name, an assistant can pass what a person said. Render the delivery note for order 4711 and mail it to dispatch is one call.
Permissions
Mailing has three permission scopes, each with the usual 
read, 
create, 
update, 
delete and 
full.
  
    
      
Scope
      
Grants
    
  
  
    
      
mailer:*
      
The Mailers master data.
    
    
      
mail-template:*
      
The Mail Templates master data.
    
    
      
report-mail-task:*
      
Seeing the Mail Queue, and 
create for actually sending mail, from the API as well as from the frontend.
    
  
report-mail-task:create is the one that matters for sending. It is checked at the start of a render, before anything is rendered, so a user without it gets a clear refusal instead of a wasted render.
Mail graphics are Common Report Resources, so maintaining them uses 
common-report-resource:*. That permission also covers the logos printed on labels, which is the price for uploading a logo once rather than twice.

Mailers: master data for your SMTP accounts
A mail needs an account to go out through. Mailers are that account as master data: one record per SMTP mailbox or relay, with its host, its credentials, the address it sends from, and the limits your provider actually enforces. Every mail VeloxFactory sends goes through one of these records.
The 
MAIL_* keys in the environment file are Laravel's own fallback mailer and are deliberately not used by report mailing. Mail configuration belongs in the application, where it can be changed, tested and audited without a deployment.
Screenshot placeholder: 
mailer.index.png
Mailers overview under Configuration with transport badges, the approval status and the Active column.
Where to find it
Mailers live in the main menu under Configuration → Mailers. The overview is a regular VeloxFactory lookup: search over name, host, sender address and description, filters for transport, active state, tested state, creator, updater and creation date, sortable columns, and the filter state kept in your session.
New opens the create form, the pencil on a row opens an existing record. Deleting is done from the edit page.
The fields of a mailer
  
    
      
Field
      
Required
      
Description
    
  
  
    
      
Name
      
yes
      
Unique, three to 55 characters, for example 
Office SMTP. This is what a render request may use instead of the ID.
    
    
      
Transport
      
yes
      
smtp for a real server, 
sendmail for the local binary, 
log to write the mail into the log instead of sending it. 
log is what makes a demo or a staging system harmless.
    
    
      
Host, Port
      
for smtp
      
The server and its port, for example 
smtp.office365.com and 
587.
    
    
      
Scheme
      
no
      
smtp for STARTTLS on port 587, 
smtps for implicit TLS on port 465. Left empty the transport decides by port, which is right for most servers.
    
    
      
Username, Password
      
no
      
Stored encrypted. The password is never returned by the API, and the edit form shows it empty: leave it empty to keep the stored one.
    
    
      
From Address
      
yes
      
The sender of every mail sent through this mailer. Many providers require it to match the authenticated mailbox.
    
    
      
From Name
      
no
      
The display name next to the address, for example 
Shipping Department.
    
    
      
Reply To
      
no
      
Where replies should go, when that is not the sender. Useful for a no-reply sender with a real support mailbox behind it.
    
    
      
Timeout
      
no
      
Seconds before the transport gives up. Relevant for synchronous sending, where the render request waits.
    
    
      
Local Domain
      
no
      
The EHLO name. Left empty the host part of the application URL is used. Some strict relays insist on a specific value.
    
    
      
Limit per minute / hour / day
      
no
      
The dispatch rate limits, see below. The hourly limit defaults to 500.
    
    
      
Description
      
no
      
Free note, for example which department the mailbox belongs to.
    
    
      
Active
      
-
      
On by default. An inactive mailer stays in the master data and keeps its history, but it can no longer be selected and no longer resolves in a render request.
    
  
Screenshot placeholder: 
mailer.edit.png
Mailer edit form with connection fields, the three rate limit fields and the remaining-slots badges.
Testing a mailer
A new or changed mailer starts as Unapproved. The edit page has a Send Test Mail button that sends a short message through exactly the configuration you just saved, to your own address by default. On success the mailer flips to Approved, on failure the transport's own error message is shown, which is usually enough to see whether it was the port, the credentials or the TLS mode.
This mirrors how report connections are verified, and it works the same way: the status is information, not a gate. A mailer that has never been tested can still be used, it is simply not marked as proven.
ℹ️ Changing a connection field resets the approval. Transport, host, port, scheme, credentials and sender address all invalidate the tested state, so a green badge always refers to the configuration that is actually stored.
A test mail consumes a rate limit slot like any other mail, so the counter stays honest. If the limit is exhausted, the test is refused with the waiting time instead of being sent.
Rate limits
Providers cap outbound mail, and they all cap differently. Exceeding the cap does not produce a polite error, it produces a blocked account, so the limits belong on the mailer, next to the credentials they protect.
Each mailer has three independent windows, each of them optional:
  
    
      
Window
      
Typical for
    
  
  
    
      
per minute
      
Relays that cap bursts, for example Office 365 at roughly 30 messages per minute.
    
    
      
per hour
      
Shared hosting mailboxes, typically 200 to 500 per hour. This is the one that defaults to 500.
    
    
      
per day
      
Mailbox providers, for example Gmail at 500 per day.
    
  
An empty field means the window is not enforced. All three empty means the mailer sends unthrottled. Check your provider's documentation and configure slightly below its cap, because the windows here are fixed rather than sliding.
A slot is spent per message, not per recipient: a mail to five people costs one slot, which is how providers count as well.
When a slot is not available, VeloxFactory does not drop the mail:
  
    
      
Path
      
What happens
    
  
  
    
      
Synchronous
      
The mail is converted into a delayed queued send. The response says so, the task stays Pending and shows when it is due.
    
    
      
Asynchronous
      
The queued job releases itself until the window opens. Waiting does not count against the retry budget, so throttling never turns into an error.
    
  
The edit page shows the remaining slots per configured window, so a run that is about to hit a cap is visible before it does.
⚠️ The queue fallback needs a running queue. If a synchronous send is pushed into the queue because of the rate limit and no Horizon worker is running, the mail waits as Pending in the Mail Queue. Nothing is lost, but nothing is sent either.
Counters are per mailer and per installation. Two VeloxFactory instances sharing one SMTP account do not share a counter.
Name resolution and deletion
A render request may address a mailer by its numeric ID or by its unique name, and only active records resolve. An unknown or inactive name is refused with a clear message before anything is rendered, rather than silently falling back to some default mailer.
A mailer cannot be deleted while a mail task still references it, so the history of what was sent stays intact. To retire a mailbox, switch the record to inactive: it disappears from every picker and stops resolving, while everything that was sent through it keeps its record.
The API
Mailers are a regular API resource under 
/api/v1/mailer, with the same envelope, the same audit segment and the same error format as every other resource.
  
    
      
Endpoint
      
Description
    
  
  
    
      
GET /mailer
      
List mailers, optionally narrowed with 
limit.
    
    
      
GET /mailer/{id}
      
A single mailer, with 
withAudit=true including its audit segment.
    
    
      
POST /mailer
      
Create a mailer. 
name, 
transport and 
fromAddress are required, 
host and 
port additionally for SMTP.
    
    
      
POST /mailer/{id}/test
      
Send a test mail, optionally to a given 
to address, and update the approval status.
    
    
      
PATCH /mailer/{id}
      
Partial update. An omitted or empty password keeps the stored one.
    
    
      
DELETE /mailer/{id}
      
Delete a mailer, refused while mail tasks still reference it.
    
  
A mailer resource is returned as:
{
    "model": "Mailer",
    "id": 1,
    "name": "Office SMTP",
    "transport": "smtp",
    "host": "smtp.office365.com",
    "port": 587,
    "scheme": "smtp",
    "username": "reports@example.com",
    "fromAddress": "reports@example.com",
    "fromName": "Shipping Department",
    "replyTo": "support@example.com",
    "timeout": 30,
    "localDomain": null,
    "rateLimitPerMinute": 30,
    "rateLimitPerHour": 500,
    "rateLimitPerDay": null,
    "rateLimitRemaining": { "minute": 28, "hour": 471 },
    "isActive": true,
    "mailerTested": true,
    "status": "Approved",
    "description": "Shipping mailbox"
}
The password is never part of the response.
AI assistants
The MCP server exposes the same operations as tools, including the test. An assistant can create a mailer from a provider's documented settings and verify it in the same conversation.
Permissions
Mailers use the standard permission scheme and have their own Mailers section in the user editor.
  
    
      
Permission
      
Grants
    
  
  
    
      
mailer:read
      
See the menu entry, the overview and a mailer's detail page. Also required to pick a mailer when sending.
    
    
      
mailer:create
      
Create mailers.
    
    
      
mailer:update
      
Change mailers, including the active state, and send test mails.
    
    
      
mailer:delete
      
Delete mailers.
    
    
      
mailer:full
      
All of the above, like 
global:admin.
    
  
Credentials are readable to anyone with 
mailer:read in the sense that the username is shown; the password is not, on any path. Treat 
mailer:update as an administrative permission.

Mail Templates: subject, body and whitelabeling
A mail needs something to say. Mail Templates are the subject and the body, written once and reused by every render that mails a document. They are edited in a WYSIWYG editor, so nobody has to write HTML, and everything variable is a placeholder that VeloxFactory fills in at send time: the trace id, a parameter of the request, the name of the report, a column of the data that was rendered.
A template decides the content. The surrounding mail, a plain card in your application's colours, is built by VeloxFactory, and a template can override parts of it when a customer needs their own look.
Screenshot placeholder: 
mail-template.edit.png
Mail Template edit page with the rich text editor, the toolbar and the placeholder and preview buttons.
Where to find it
Mail Templates live in the main menu under Configuration → Mail Templates. The overview is a regular VeloxFactory lookup with search over name, subject and description, a filter for the active state and the usual audit filters.
A template has a unique name, which is what a render request may use instead of the ID, a subject, a body and an active flag. An inactive template stays in the master data but is no longer offered and no longer resolves.
The editor
The body is written in a rich text editor built into VeloxFactory. No add-on, no external service, and nothing to learn: the toolbar does what a toolbar does.
  
    
      
Group
      
Tools
    
  
  
    
      
Text
      
Bold, italic, underline, headings, paragraph, bullet and numbered lists, text colour and remove colour, clear formatting.
    
    
      
Links
      
Insert, edit and remove links. With the caret inside an existing link, the link tool edits that link instead of creating a new one. With nothing selected, it inserts the URL itself as the link text. Only 
http, 
https and 
mailto are accepted, and every link is marked so it opens safely.
    
    
      
Tables
      
Insert a table with a chosen number of rows and columns and an optional header row, then insert or delete rows and columns from wherever the caret sits.
    
    
      
Images
      
Insert a graphic from the Common Report Resources, with an optional width.
    
    
      
Buttons
      
Turn paragraphs into a button, change its colours or remove it again. See Buttons and callouts below.
    
    
      
Callouts
      
Frame paragraphs as an Info, Warning or Danger box, change its type or remove it again. See Buttons and callouts below.
    
    
      
Placeholders
      
Insert a placeholder at the caret, chosen from the catalog.
    
  
Pasting is deliberately plain text. Formatted content dragged in from Word or a browser is the single most common reason a mail looks broken in one client and fine in another, so the editor strips it and keeps the words.
Whatever the editor produces is cleaned on the server against an allowlist before it is stored. That is not a formality: it is what guarantees that a template cannot carry a script, a tracking pixel or an arbitrary external image, no matter what was pasted into it.
Placeholders
Anything in square brackets is replaced when the mail is built. Both the subject and the body support them.
Hello [contactName], attached is your report [report.name] with the trace ID [traceId], rendered on [now.dateLocale].
The Placeholders button opens a dialog listing every token that is available, grouped, with a description and an example, and each one copyable with a click. Opened from a template that is tied to a report, the parameter and field tokens are expanded to the real names of that report.
  
    
      
Group
      
Examples
    
  
  
    
      
General
      
[traceId], 
[reportFileName] (the attachment name), 
[reportUrl], 
[outputType], 
[appName], 
[contactName], 
[broadcastId]
    
    
      
Generic
      
[now.date], 
[now.dateLocale], 
[now.dateTime], 
[now.weekday], 
[now.monthName], 
[now.weekNumber], 
[now.quarter]
    
    
      
Report
      
[report.name], 
[report.description], 
[report.context], 
[report.connection]
    
    
      
History Record
      
[historyRecord.id], 
[historyRecord.status], 
[historyRecord.url] as a direct link into VeloxFactory
    
    
      
User, API Token
      
[user.name], 
[user.email], 
[token.name] - who or what triggered the render
    
    
      
Printer
      
[printer.name], 
[printer.copies] when a print task was created alongside
    
    
      
Parameters, Data
      
[parameters.P_ORDER_NO], 
[data.count], 
[data.first.CUSTOMER], 
[data.last.ARTICLE]
    
    
      
Recipients
      
[recipients.toCount], 
[recipients.ccCount], 
[recipients.bccCount]
    
    
      
Environment
      
[env.appEnv], 
[env.hostname], 
[env.timezone] - to mark a mail from a test system as such
    
    
      
Images
      
[image.logo_dark] - one entry per usable Common Report Resource
    
  
ℹ️ An unknown placeholder never breaks a mail. It resolves to an empty string and is reported back to the caller, so a typo shows up as a gap and a note, not as a failed send.
ℹ️ Placeholder values are inserted as text. A resolved value that happens to contain markup, for example a customer name with a 
<b> in it, appears literally in the mail instead of changing its formatting. The markup you set in the editor is unaffected.
The same catalog is available beyond subject and body: recipients, contact name and the names the attachments carry in the mail accept placeholders too. See the Report Mailing page for how that behaves.
Graphics
Mail graphics are the Common Report Resources you already maintain, the same PNG and JPEG files the reports use. A logo is uploaded once and serves both a printed label and a mail.
Insert one with the image button, or type its placeholder, for example 
[image.logo_dark]. Both produce the same thing, and the editor shows the graphic while you write.
At send time the graphic is embedded into the mail as an inline attachment, not linked from a server. That matters for two reasons: the mail is self-contained, so it also works for a recipient outside your network, and no client shows a load external images bar or treats it as a tracking pixel.
ℹ️ Only graphics from the master data. An image pasted in from a website is removed when the template is saved. If a graphic should be in a mail, upload it under Configuration → Common Report Resources and reference it by name.
A Common Report Resource that a template embeds cannot be deleted or renamed while the template uses it. The refusal names the template, so it is clear what would break.
Buttons and callouts
A report mail usually has one thing the recipient should do, open the report, confirm an order, check a status, and sometimes one thing they must not overlook. Buttons and callouts make both stand out, without anyone writing HTML and without fighting the rendering quirks of Outlook.
Screenshot placeholder: 
mail-template.blocks.png
The editor with a button, its colour popover and the three callout types.
Buttons
The button tool in the toolbar (icon 
smart_button) turns the paragraph the caret is in into a button. With a selection, every selected paragraph becomes a button. On an empty line it inserts a new button with the text Button text, ready to be overwritten.
A button holds whatever a paragraph holds. Links are set with the usual link tool, and the URL can mix text and placeholders, for example 
https://example.com/report/[traceId]. If the button consists of nothing but a link, the whole button area is clickable, not only the words. Centre the paragraph inside the button and the button itself is centred in the mail.
  
    
      
Setting
      
Behaviour
    
  
  
    
      
Background
      
The header colour of the mail by default. That is the colour the mail actually uses, so a template with its own header colour override gets buttons in that colour. The checkbox Header color returns a changed background to this default.
    
    
      
Text
      
White by default. The checkbox White returns a changed text colour to this default.
    
  
Both colours are set per button in the popover of the button tool. To change an existing button, click into it and then on the tool: Apply stores the new colours, and the same popover removes the button again.
Callouts
The callout tool (icon 
format_quote) puts a box around the paragraphs the caret is in, or around all selected paragraphs. There are three types:
  
    
      
Type
      
Look
    
  
  
    
      
Info
      
Left border in the header colour of the mail, grey background. For notes and context.
    
    
      
Warning
      
A ⚠ triangle, amber border, light yellow background. For something the recipient should check.
    
    
      
Danger
      
Red border, light red background. For errors and things that must not be missed.
    
  
With the caret already inside a callout, the tool changes its type or removes the callout again.
What you see while writing
The editor shows buttons and callouts roughly as they will appear in the mail. The button colour follows the header colour of the whitelabeling live, so switching the override on or changing its value recolours the buttons in the editor at once. For the exact result, use the Preview.
How they are stored and sent
A template does not store the finished mail markup of a button or callout. It stores a lean marker, 
<div data-mail-button> for a button and 
<div data-mail-callout="…"> with the type for a callout. The server allowlist lets both markers through and removes a callout type it does not know.
The real markup, tables with inline styles that Outlook also renders correctly, is built only when the mail is displayed: when it is sent, in the Preview and in the Mail Queue. All three therefore always use the current header colour of the mail.
ℹ️ A later header colour change reaches existing mail tasks. Because buttons and callouts are built at display time, a mail task that already exists picks up a later change of the header colour for its buttons and callouts when it is shown in the Mail Queue or sent again.
Whitelabeling
By default every mail looks the same: a card in the colours of your VeloxFactory installation, read straight from the application's stylesheet. On top sits a dark header bar in the secondary dark colour of the theme (
#2D3432 in the standard theme) with the logo, directly beneath it a 4 px line in the primary colour, then the content and a footer. Table headers in the body carry the primary colour as well. Change a colour in the frontend and the mails follow, without touching a template.
When one customer or one process needs something else, a template can override parts of that frame. Each override has its own switch, and switching it off returns that part to the global default:
  
    
      
Override
      
Effect
    
  
  
    
      
Header colour
      
The colour of the header bar, instead of the dark default. Table headers in the body follow it, and so do the default background of buttons and the border of Info callouts. The line beneath the header keeps its own colour.
    
    
      
Header line colour
      
The colour of the 4 px line beneath the header, instead of the primary colour.
    
    
      
Hide header line
      
No line beneath the header, so the header bar meets the content directly.
    
    
      
Body colour
      
The background of the content area, instead of white.
    
    
      
Logo
      
A different Common Report Resource in the header, instead of the configured logo.
    
    
      
Hide logo
      
No logo at all, for a plain header.
    
    
      
Footer text
      
A different footer line. Supports the full placeholder catalog, so it can carry a trace id, a contact or a legal note.
    
  
Screenshot placeholder: 
mail-template.whitelabel.png
The whitelabeling block with the per-field switches for header colour, header line colour, hide header line, body colour, logo and footer text.
Colour and visibility of the header line show up in the preview of the edit page right away, before the template is saved, so a customer colour can be tried out against the real frame instead of guessed.
The failure notice the Job Scheduler sends when a scheduled job fails uses the same frame, dark header and primary colour line included, so both kinds of mail look alike. It is not bound to a template and has no overrides.
Preview
The Preview button renders the template inside the real mail frame, with example values or against an existing history record, and shows it in a dialog. It is the same rendering path the actual mail uses and the same one the Mail Queue uses to show a sent mail, so the three cannot drift apart: what the preview shows is what is sent and what is archived.
Use it after every change. It is the fastest way to catch a placeholder that resolves to nothing, a table that lost its borders or a whitelabel colour that makes the text unreadable.
The API
Mail Templates are a regular API resource under 
/api/v1/mail-template.
  
    
      
Endpoint
      
Description
    
  
  
    
      
GET /mail-template/placeholders
      
The placeholder catalog, optionally expanded for a given 
reportConfig.
    
    
      
GET /mail-template
      
List templates.
    
    
      
GET /mail-template/{id}
      
A single template, with its audit segment on request.
    
    
      
POST /mail-template
      
Create a template. The body is sent Base64-encoded and is cleaned against the allowlist before it is stored. The description of 
bodyHtmlBase64 lists the two markers for buttons and callouts, for integrations that send HTML directly.
    
    
      
POST /mail-template/{id}/preview
      
Render subject and body, with example values or against a history record, and report which placeholders stayed unresolved.
    
    
      
PATCH /mail-template/{id}
      
Partial update.
    
    
      
DELETE /mail-template/{id}
      
Delete a template, refused while mail tasks still reference it.
    
  
The whitelabel settings are regular fields of the resource, for example 
headerLineColor for the line colour and 
hideHeaderLine for the switch. Left empty or off, each one falls back to the global default.
Unknown placeholders in a stored template are not an error. They are returned as messages, so an integration can warn without being blocked.
AI assistants
The MCP server exposes the same operations, including the placeholder catalog. An assistant can therefore write a template that uses the real parameter names of a specific report, and preview it before anyone sends it.
Permissions
Mail Templates use the standard permission scheme and have their own Mail Templates section in the user editor.
  
    
      
Permission
      
Grants
    
  
  
    
      
mail-template:read
      
See the menu entry, the overview and a template. Also required to pick a template when sending.
    
    
      
mail-template:create
      
Create templates.
    
    
      
mail-template:update
      
Change templates, including the whitelabeling and the active state.
    
    
      
mail-template:delete
      
Delete templates.
    
    
      
mail-template:full
      
All of the above, like 
global:admin.
    
  
Uploading the graphics a template uses is a separate permission, 
common-report-resource:create and 
:update, because those files are shared with the reports.

Schedule your jobs
The Job Scheduler: renders and the consolidated cleanup, on a crontab expression or at a single date and time, operable through the API.

The Job Scheduler: work that happens without you
Most of what VeloxFactory does happens because something asked for it: a request comes in, a report is rendered, a label goes to a printer. Some work has no caller, though. A shift report that should be in the supervisor's mailbox at six every morning. The cleanup that keeps the history from growing forever. Work like that runs on a clock, not on a request.
The Job Scheduler is where that clock lives. Every job is a record with a timezone and an active flag, and it says when it runs either as a crontab expression or as a single date and time. Schedules are maintained in the frontend or through the API like any other master data. VeloxFactory itself runs one fixed entry: every minute it looks for schedules that are due and hands them to the queue.
Screenshot placeholder: 
scheduler.overview.png
The Job Scheduler overview with type, cron expression, next run, last run and status per schedule.
Two kinds of schedule
  
    
      
Type
      
What it does
    
  
  
    
      
Render Job
      
Fires a complete render request on a schedule: parameters, data rows, printing, history record and the full mailing segment. Everything a render can do from the API, a schedule can do at four in the morning.
    
    
      
Purge Job
      
The housekeeping: print tasks, mail tasks, history records, orphaned files and the scheduler's own run log, each with its own retention in days. One schedule, one run, a fixed order.
    
  
One Purge Job covers all five kinds of cleanup, so there is a single place to say when housekeeping happens and how long each entity is kept. A fresh instance already has the schedule, deactivated and without a cron expression, so nothing runs until you decide when it should.
Saying when
A schedule accepts full five field crontab syntax, the same thing every operations person already knows. You do not have to write it by hand: the editor has a guided mode with frequency, time and weekday pickers, and an expression mode for everything the guided mode cannot express. Both write into the same field, and whichever you use, the next run times are shown underneath while you type.
  
    
      
Expression
      
Meaning
    
  
  
    
      
0 6 * * 1-5
      
Weekdays at 06:00, the shift report.
    
    
      
*/15 * * * *
      
Every quarter of an hour.
    
    
      
0 3 1 * *
      
The first of every month at 03:00, the monthly statement.
    
    
      
empty
      
Never fires on its own. The schedule exists and can be started by hand, which is how you test one before switching it on.
    
  
Every schedule carries its own timezone, defaulting to the timezone of the instance. That matters for a company that renders for a plant in another country: the expression says 06:00 and the timezone says which 06:00.
Daylight saving time: an expression that points into the hour the clock skips or repeats runs twice in October and not at all in March. For a job that has to happen exactly once a day, pick a time outside 02:00 to 03:00.
Running once, at a given time
Not every job repeats. A price list that has to go out on the day the new catalogue takes effect, a cleanup that belongs to one migration: those are a point in time, not a pattern. A schedule therefore says when it runs either with a cron expression or with a single date and time, never with both.
{
    "runAt": "2026-10-25 17:35",
    "deactivateAfterRun": true
}
In the form the field is Run once at, with a date and a time picker, next to the switch Deactivate after the run. A one-time schedule shows Once in the overview instead of an expression, and its date on the detail page and in the next run preview.
  
    
      
Question
      
Answer
    
  
  
    
      
Which clock does the time follow?
      
The timezone of the schedule, or the timezone of the instance when the schedule has none. A value that carries its own offset, such as 
2026-10-25T17:35:00+02:00, wins over both. The API answers with the time in the schedule's timezone.
    
    
      
Cron and date together?
      
Refused with 422. To turn a one-time schedule into a recurring one, send 
runAt: null together with the cron expression.
    
    
      
A date in the past?
      
A date that is being set or changed has to lie in the future. A date that already passed does not block edits to the other fields of the schedule.
    
    
      
What happens after the run?
      
The date is used up: there is no next run and the schedule does not fire again. That also holds when the slot was discarded after a long outage of the scheduler, or when the worker died in the middle of the run.
    
    
      
And the schedule itself?
      
With Deactivate after the run it sets itself inactive. Without it the schedule stays active but has nothing pending; give it a new date to arm it again.
    
    
      
Does Run now use the date up?
      
No. A manual run is a test, the pending date stays where it is.
    
  
A one-time Purge Job counts as an active cleanup for as long as its date is still ahead, so the overview does not warn about missing housekeeping while one is armed.
What happens when a schedule is due
Every minute VeloxFactory collects the schedules whose next run has arrived, moves each one to its following slot and hands it to the queue. The order matters: the next slot is written first, so a schedule can never fire the same slot twice, whatever happens afterwards. A schedule that runs once has no following slot, so its slot is cleared instead of moved on, which is what makes it fire exactly once.
Three things are deliberately not done.
Missed slots are not made up. If the scheduler was stopped for three hours, the slots in between are gone. One late run within the grace window is fired, anything older is recorded as skipped so you can see that it happened.
Runs of one schedule never overlap. A render that takes longer than its own interval simply keeps running; the next run is recorded as skipped rather than queued behind it. Two different schedules do run side by side.
A run is not retried. A second attempt would print a second label and send a second mail. A failed run ends as an error and says why.
Who a render job runs as
A scheduled render is a real render request, so it needs somebody to make it. That somebody is the user who created the schedule, and the schedule carries one of that user's API tokens to run with. Nothing else changes: the same permissions apply, the same audit columns are filled, and the history record shows who and which token, exactly as if the request had come over HTTP.
Two consequences are worth knowing before you build a schedule around a colleague who is about to change roles.
If the owner is set inactive, or the token is revoked or expires, the run stops before anything is rendered. It is recorded as skipped with the reason, and the failure mail goes out.
Because a render job acts with its owner's permissions, only the owner and administrators may change its configuration or start it by hand. Everyone with the read permission can see it and read its log.
The token is referenced, never stored. VeloxFactory keeps only the hash of a token, so a schedule points at the token record you pick from a list, and revoking that token stops the schedule the same minute.
API tokens expire after the period configured in 
SANCTUM_EXPIRATION, one year by default. A schedule whose token has lapsed stops with the same error as a revoked one and sends the configured failure mail. Owners of long-running schedules should issue themselves a fresh token before the old one expires.
Screenshot placeholder: 
scheduler.render-form.png
The form of a render job: cron builder, report config, API token, output settings, parameters with the placeholder switch and the mailing block.
The run log
Every run writes a record, whether it worked or not. The log carries the trace id, so a scheduled render can be followed through the history record, the print task and the mail task it produced, and back again.
  
    
      
Status
      
Means
    
  
  
    
      
Success
      
Everything the schedule asked for happened.
    
    
      
Warning
      
The job ran, but something inside it did not: the render worked and the mail did not, a placeholder stayed empty, one purge step failed while the others finished.
    
    
      
Error
      
The job itself failed. The message from the API is on the record.
    
    
      
Skipped
      
The run never started: the previous one was still going, the owner or the token was not usable, or the slot was older than the grace window.
    
    
      
Running
      
In progress right now.
    
  
A run also records whether it was fired by the clock or started by hand, so a test run is never mistaken for a scheduled one.
Being told when something breaks
A schedule that quietly stops working is worse than no schedule at all. Every schedule can name a mailer and a list of recipients for its failure mail, which goes out when a run ends as an error or is skipped. A warning does not mail: the render happened, and the detail is already on the history record or the mail task.
These recipients are plain addresses. Placeholders belong to the mail of a document, which is resolved from the render it belongs to, and a run that failed has no render to resolve anything against.
A schedule that fires every minute and fails every minute would otherwise fill a mailbox, so the failure mail is throttled to one per schedule per hour. The window is a setting of the instance, the runs in between count how many were suppressed, and the log still has every one of them.
AI assistants
The MCP server exposes the Job Scheduler the way it exposes the rest of VeloxFactory: schedules and their run log have their own tools, a crontab expression can be validated and its next run times read back before anything is saved, and a schedule can be started once by hand to see what it does. Because report configs, mailers and templates are resolved by name, a schedule is built from what a person said. Send the shift report to the supervisor every weekday at six is one request.
The retentions of the Purge Job have their own tool, because the API expects the complete retention map in every write and a single changed value would otherwise be refused.
Permissions
The Job Scheduler has one permission scope, 
scheduled-job:*, with the usual 
read, 
create, 
update, 
delete and 
full. The run log is covered by the same scope.
Two rules go beyond the usual pattern, both for the same reason: a schedule can act with somebody else's rights, or with nobody's.
Creating a schedule implies being allowed to render, print and mail with it, so 
scheduled-job:create grants what a render needs, the way 
scan2print:use does for the scan station.
A Purge Job has no owner at all, so whoever switches a cleanup step on has to hold the permission to delete what that step deletes. Turning on the history step needs the right to delete history records.
Deleting a schedule is not limited to its owner. Deleting only stops a schedule, it can never make one act with somebody's permissions.
The Purge Job is deletable like any other schedule. With no active purge schedule, nothing cleans up history records, print tasks, mail tasks or orphaned files any more, and the disk keeps filling. The overview warns while that is the case. To bring the schedule back, use New and then Purge Job in the frontend, or run 
php artisan scheduler:create-purge-job on the server.
What has to be running
The Job Scheduler depends on the two background processes VeloxFactory runs in production.
  
    
      
Process
      
Why
    
  
  
    
      
Scheduler
      
The minute tick that finds due schedules. Without it nothing fires at all.
    
    
      
Horizon
      
The runs themselves. They have their own queue and their own worker, so a scheduled render that takes minutes never blocks a thumbnail or a mail.
    
  
Both belong under Supervisor in production. The Administration chapter has the details.

Render Jobs: a render request with a clock attached
A Render Job is a render request that VeloxFactory keeps and sends to itself. Whatever you can put into a call to the render endpoint goes into the schedule: parameters, data rows, the printer, the history record, the complete mailing segment. Nothing about rendering is special-cased for schedules, which is the point. A request you have tested once from the API behaves exactly the same at four in the morning.
Screenshot placeholder: 
scheduler.render-parameters.png
Parameters and data rows of a render job, with the placeholder switch active on a date parameter.
What you configure
  
    
      
Part
      
What it decides
    
  
  
    
      
Report Config
      
Which report is rendered. Exchangeable later in the frontend and through the API, and the payload is revalidated against the report it now points at.
    
    
      
API token
      
Which of the owner's tokens the run authenticates with. Only tokens of the owner are accepted, and only ones that are neither revoked nor expired.
    
    
      
Output
      
What the render produces, and whether a history record is written.
    
    
      
Printing
      
Printer, number of copies and broadcast id, exactly as on the generate page.
    
    
      
Parameters and data rows
      
The values the report is rendered with, entered in the same table as on the generate page, here with placeholders allowed.
    
    
      
Mailing
      
The same block as everywhere else: mailer, template, recipients, attachments, background sending.
    
  
The type and the owner are the two things a schedule keeps for its whole life. A render job stays a render job, and it stays the user who created it, because that is whose permissions every run acts with.
ℹ️ A schedule runs even when its owner cannot use the API. The scheduler calls the render internally and does not pass the API middleware, so 
global:use-api is not required for a schedule to fire. What does stop a run: a revoked or expired token, a token that no longer belongs to the owner, a deactivated owner, or a missing resource permission.
Output types
A schedule offers three of the four output types.
  
    
      
Type
      
Use it when
    
  
  
    
      
url
      
The usual choice. The PDF lands on the history disk, stays downloadable from the history record and is what a mail attaches.
    
    
      
base64
      
Same file, plus the document inside the history record. Comfortable, and noticeably larger per run.
    
    
      
none
      
Printing only. A print task is mandatory with it, the same rule the API applies.
    
  
preview is refused. A preview render deletes its own file again, so unattended it would produce nothing at all.
none and mailing do not go well together. Output type 
none produces no PDF, so a mailing that wants to attach one gets a mail without its attachment. Saving is not refused, the form says so as a note, and the honest combinations are 
none with 
includePdf: false, or 
url.
Placeholders in parameters
A schedule that renders yesterday's figures every morning cannot have a fixed date in its parameters. Parameters and data rows therefore accept placeholders, resolved fresh at the start of every run.
Only those placeholders that exist before a render are offered here, so no 
[data.first.*] and no 
[report.*]: those describe a render that has not happened yet.
  
    
      
Placeholder
      
Resolves to
    
  
  
    
      
[now.date], 
[now.dateTime], 
[now.time]
      
The moment the run starts.
    
    
      
[now.year], 
[now.month], 
[now.weekNumber], 
[now.quarter]
      
Period markers, for reports that select by week, month or quarter.
    
    
      
[traceId]
      
The trace id of this run, so the document can carry the id the log shows.
    
    
      
[uuid]
      
A fresh UUID, the same value everywhere it appears in one run and a new one in the next.
    
    
      
[user.name], 
[token.name]
      
The owner of the schedule and the token it runs with.
    
    
      
[env.hostname], 
[appName], 
[appUrl]
      
Which instance produced the document.
    
  
The Placeholders button above the parameter table lists all of them with a description and an example, and copies a token with one click. 
GET /scheduled-job/placeholders returns the same catalogue.
Typed fields need the switch. A date parameter is a date picker and a number parameter is a number field, and neither accepts 
[now.date] as text. The small button next to the field turns it into a text field for exactly that reason, and back again. Boolean parameters have no switch: a toggle has no text state, so they take no placeholders.
In the mailing block placeholders work as they do everywhere, and there the full catalogue applies: recipients, contact name and attachment names are resolved after the render, so 
[data.first.customerEmail] addresses the rows the report actually fetched.
Checked when you save, not at four in the morning
A schedule that cannot possibly succeed is refused while you are still looking at the form.
Every required parameter of the report has a value or a resource override, named individually if not.
The owner holds the permissions the run will use: reading report configs, creating print tasks when a printer is configured, creating mail tasks when there is a mailing block.
Mailer and mail template of the mailing block exist and are active.
Every resource override path points inside the resources folder of the instance, the same check the render applies.
The token belongs to the owner and is neither revoked nor expired.
The cron expression is valid five field syntax, and a date for a single run lies in the future while you are setting or changing it.
No 
traceId in the payload: every run makes its own, and a stored one would let the first run succeed and every one after it fail.
From the API
The schedule itself is ordinary master data. Its 
payload is the body you would have sent to the render endpoint.
{
    "name": "Morning shift report",
    "type": "render",
    "cron": "0 6 * * 1-5",
    "timezone": "Europe/Berlin",
    "isActive": true,
    "reportConfig": "Shift Report",
    "token": 17,
    "errorMailer": "Office SMTP",
    "errorTo": ["ops@example.com"],
    "payload": {
        "outputType": "url",
        "parameters": { "P_DATE": "[now.date]", "P_RUN": "[uuid]" },
        "createPrintTask": false,
        "createHistoryRecord": true,
        "mailing": {
            "mailer": "Office SMTP",
            "mailTemplate": "Shift Report",
            "to": ["supervisor@example.com"],
            "includePdf": true,
            "pdfFileName": "Shift_[now.date]",
            "sendAsync": true
        }
    }
}
reportConfig, 
errorMailer and the mailer and template inside the payload accept either the numeric ID or the unique name, the same way the render endpoint does.
A job that is meant to happen once carries 
runAt in place of 
cron, and says with 
deactivateAfterRun whether it switches itself off afterwards:
{
    "cron": null,
    "runAt": "2026-10-25 17:35",
    "deactivateAfterRun": true
}
Both fields come back on every read, 
runAt in the timezone of the schedule. Sending 
cron and 
runAt together is refused with 422, and 
runAt: null together with an expression turns the schedule back into a recurring one.
  
    
      
Endpoint
      
Does
    
  
  
    
      
GET /scheduled-job
      
Lists schedules, filterable by 
type and 
isActive.
    
    
      
GET /scheduled-job/{id}
      
A single schedule with its payload, its owner and its token.
    
    
      
POST /scheduled-job
      
Creates one. The caller becomes the owner.
    
    
      
PATCH /scheduled-job/{id}
      
Changes it. Type and owner are refused, everything else you leave out keeps its stored value.
    
    
      
DELETE /scheduled-job/{id}
      
Deletes the schedule and its run log.
    
    
      
POST /scheduled-job/{id}/run
      
Queues a run right now, with the owner's identity, not the caller's. A pending single run stays pending.
    
    
      
POST /scheduled-job/preview-cron
      
Validates an expression and answers with the next run times in a timezone.
    
    
      
GET /scheduled-job/placeholders
      
The catalogue a schedule may use, for building your own form.
    
    
      
GET /scheduled-job-run
      
The run log, filterable by schedule and status.
    
    
      
GET /scheduled-job-run/{id}
      
One run with its trace id, its result summary and its error message.
    
    
      
DELETE /scheduled-job-run/{id}
      
Deletes one run record. What the run produced is untouched.
    
  
Changing or starting a render schedule is limited to its owner and to administrators, because the run acts with the owner's permissions. Reading it, and reading its log, needs 
scheduled-job:read like any other lookup.
Trying it before you trust it
Leave the cron expression empty, save, and press Run now. The schedule never fires by itself, the run is recorded as a manual one, and you get the same result you would get at six in the morning: a history record, a print task if you configured a printer, a mail task if you configured mailing, and a line in the run log with the trace id that ties them together.
A schedule that is waiting for its single date can be tested the same way. Run now is a test run, not the appointment, so the date stays where it is.
When it does what you want, add the expression and switch the schedule on.

The Purge Job: one schedule for all cleanup
An instance that renders all day accumulates. History records with their PDFs, print tasks that have long been printed, mail tasks whose mails arrived weeks ago, and files on the history disk that no record points at any more. Somebody has to take that out, on a clock, without anybody thinking about it.
The Purge Job is that somebody. One schedule, one run, five entities, five retentions.
Screenshot placeholder: 
scheduler.purge-form.png
The purge settings with one retention field per entity and the switch that turns a step off.
The five steps
  
    
      
Step
      
Deletes
    
  
  
    
      
1. Print Tasks
      
Print tasks past the retention that have reached status 
Printed. One that never printed stays, so a problem does not disappear before anybody looked at it.
    
    
      
2. Mail Tasks
      
Mail tasks past the retention, whatever their status. The mail itself is long gone, the record is the receipt.
    
    
      
3. History Records
      
History records past the retention, together with their PDF and their xlsx export.
    
    
      
4. Orphaned Files
      
Files on the history disk that no history record and no mail task refers to any more, and that are older than the retention.
    
    
      
5. Scheduler Run Log
      
The run records of the Job Scheduler itself. The run doing the deleting never deletes itself.
    
  
The order is fixed and not configurable. Print tasks and mail tasks point at the history records they belong to, so the database refuses to delete a record while one of them still references it. Running the steps in this order is what makes the cleanup work, and it is the reason all five belong in one schedule instead of five.
Saying how long
Every step has its own retention in days, and every step can be switched off on its own.
  
    
      
Value
      
Means
    
  
  
    
      
90
      
Delete what is older than 90 days.
    
    
      
0
      
Delete everything older than right now. Useful for a one-off clear-out, dangerous as a standing setting.
    
    
      
switched off
      
That entity is never purged. The step is named under 
skipped in the run result, so the log shows it was a decision and not an accident.
    
  
A sensible starting point keeps print and mail tasks shorter than the history records they belong to, and the orphaned files shortest of all. Something like 30, 30, 90, 7 and 90 days.
Saying when
A purge schedule says when it runs the same way every other schedule does: with a cron expression for the nightly housekeeping, or with a single date and time for a cleanup that belongs to one occasion, such as the clear-out after a migration. Both are on the Job Scheduler page.
A purge schedule that is waiting for its single date counts as active cleanup for as long as that date is still ahead, so the overview does not warn about missing housekeeping while one is armed. Once it has run, that cleanup is over; a 0 retention that was meant for exactly that one run does not stay armed for the next night.
Where it comes from
The base setup of an instance creates the schedule under the name Purge Job, deactivated and without a cron expression. Its five retentions start from the 
PURGE_*_DAYS keys of the 
.env file, which are read once at that moment. From then on the retentions live on the schedule, and the 
.env keys are not read again.
Nothing is cleaned up until you give the schedule an expression and switch it on. That is deliberate: a fresh instance should not start deleting on a schedule nobody chose.
0 3 * * *     every night at 03:00
0 3 * * 0     Sunday nights only, for an instance with little traffic
Who may switch a step on
A Purge Job has no owner. It runs without any user at all, which means the usual permission check has nothing to check against. So the check moves to the moment a step is configured: whoever switches a step on, or changes its retention, has to hold the permission to delete what that step deletes.
  
    
      
Step
      
Needs
    
  
  
    
      
Print Tasks
      
report-print-task:delete
    
    
      
Mail Tasks
      
report-mail-task:delete
    
    
      
History Records, Orphaned Files
      
report-history-record:delete
    
    
      
Scheduler Run Log
      
scheduled-job:delete
    
  
Steps you leave untouched are not asked about again, so somebody may change the cron expression without holding every delete permission in the instance.
What a run tells you
The run record carries the numbers per step: how many records were eligible, how many were deleted, how many could not be. A step that throws does not stop the ones after it.
  
    
      
Outcome
      
Status
    
  
  
    
      
Every configured step finished
      
Success
    
    
      
Some steps finished, one failed or left records behind
      
Warning, with the reason in the result
    
    
      
Every configured step failed
      
Error, and the failure mail goes out
    
  
A history record that could not be deleted because something still references it is logged individually, not swallowed into a count.
Doing it by hand
The first four steps are each available as an artisan command as well, for a one-off cleanup or a maintenance window.
php artisan report-print-tasks:purge --days=30
php artisan report-mail-tasks:purge --days=30
php artisan report-history-records:purge --days=90
php artisan orphaned-files:purge --days=7
Run them in that order for the same reason the schedule does.
If the schedule is gone
The Purge Job is an ordinary schedule and can be deleted like any other. Nothing then cleans up, and the disk keeps filling. The Job Scheduler overview shows a warning for as long as no active purge schedule exists.
There are two ways back, and neither of them is special.
From the frontend. New on the Job Scheduler overview offers Purge Job next to Render Job. Pick it, set the retentions, give it a cron expression and switch it on. A purge schedule is created like any other schedule; it needs no owner and no API token, only a name that is still free and the delete permissions of the steps you switch on. The same way you would create a second one, for instance a weekly run with longer retentions next to a nightly one.
From the command line, for an instance you would rather not click through:
php artisan scheduler:create-purge-job
It creates the schedule under its original name when it is missing and does nothing when it is already there. It touches neither storage nor users, so it is safe on a live system. Afterwards give it its cron expression and switch it on again.

Customer case studies
What customers built with VeloxFactory, and what it replaced.

PPWR Compliance Documents at Scale
Customer
      
Zeller Present Handels GmbH
      
    
    
      
Industry
      
Home and lifestyle products: kitchen, table, home & living, bath, office, kids
    
    
      
Project
      
PPWR document generation with ERP integration
    
    
      
Project duration
      
approx. 4 weeks
    
  
Overview
Zeller Present supplies home and lifestyle products for kitchen, table, home & living, bath, office and kids, sold through retail partners and its own online shop. The company has to comply with the EU Packaging and Packaging Waste Regulation (PPWR, Regulation (EU) 2025/40). For every packaging it places on the market, the regulation requires an EU declaration of conformity and technical documentation. With an assortment of around 2,200 articles, each shipped in up to three packaging levels and documented in two languages, writing these documents by hand was not an option.
As part of a project, kiwi software connected Zeller Present's ERP system Alphaplan 5 to VeloxFactory and developed a small middleware between the two systems. At the push of a button, or automatically once a month, VeloxFactory now produces up to 12 compliant documents per article, which are filed, versioned and published without any manual step.
The Challenge
The regulation turns every packaging level into its own documentation task. What Zeller Present needed:
One declaration of conformity and one technical documentation per packaging level: individual packaging, outer carton and master carton
Every document in German and English
Around 2,200 articles with up to 12 documents each, up to roughly 26,000 documents in total
Documents that stay in sync with ERP master data: when a dimension or a material weight changes, the affected documents must be reissued
Previous versions retained for traceability
The complete, current document set available for download by customers and authorities
The Solution
kiwi software handled the ERP integration and built a lightweight middleware that sits between Alphaplan 5 and VeloxFactory. The middleware reads the packaging master data from the ERP, derives all document values and renders every document through VeloxFactory's REST API. The workflow:
The middleware selects all assortment articles that have no documents yet, or whose PPWR-relevant master data has changed since the last run, based on the ERP change log
For each article, it detects the packaging levels present: individual packaging, outer carton and master carton
It derives the values the regulation asks for: packaging type from the material weights, dimensions, weights, silica content, and the void ratio of outer and master cartons
For each packaging level, it calls VeloxFactory four times: declaration of conformity and technical documentation, each in German and English
The PDFs are filed on the document drive; any previous version is moved to a dated archive folder
The ERP receives a timestamp on the article, so it is only processed again when relevant data changes
Finally, one ZIP archive per language with the complete document set is uploaded to a public download server, and an info mail reports the result
The middleware runs the process automatically on the first day of every month and can be started at any time from the web interface. Since only new or changed articles are processed, an additional run is always safe.
Technical Setup
Component
Details
Trigger
Scheduled job (monthly) and manual start from the web interface
ERP
Alphaplan 5 on MS SQL Server
Middleware
Lightweight Laravel middleware between ERP and VeloxFactory, developed by kiwi software as part of the project
Report engine
VeloxFactory, self-hosted on premises
Report templates
4 Jaspersoft Studio templates (.jrxml): declaration of conformity and technical documentation, German and English
Data transfer
Parameters only, no SQL in the templates; up to 15 parameters per document
API call
POST /report-config/{id}/render with Base64 output, laconic response, no history record
Output
Up to 12 PDFs per article, versioned on the document drive, one ZIP archive per language
Volume
~2,200 articles, up to ~26,000 documents
Static content such as manufacturer details, signatory, legal references and the conformity assessment module lives in the report templates. Everything that varies per article and packaging level arrives as a parameter in the render request.
Results
The PPWR documentation for Zeller Present's entire assortment is now generated and maintained automatically:
Up to 12 compliant documents per article, in German and English, without manual work
Documents follow master data changes: only affected articles are regenerated
Every previous version is archived with its date
Consistent document numbers and layout across the whole assortment
The public download archive is always complete and up to date
Why VeloxFactory
VeloxFactory itself needed no changes for this project. The middleware, where the ERP knowledge lives, derives all values; VeloxFactory turns them into finished PDFs with one REST call per document. This kept the middleware small: no report engine, no PDF library and no layout code inside it.
Legal texts and layout sit in standard 
.jrxml templates, so wording can be updated without touching the middleware. For a run of this size, 
laconicResponse and disabled history records keep every response small and the database lean.
Published with the kind permission of Zeller Present Handels GmbH.

Administration
Running an instance: background processes, queues and maintenance.

Background Job Processing
VeloxFactory processes background work through a Redis-backed queue managed by Laravel Horizon: thumbnail generation, mail dispatch, and everything the Job Scheduler fires. Horizon runs as a single supervised process and manages its own worker pool internally, with dynamic scaling, real-time monitoring and a built-in dashboard.
Prerequisites
Horizon has two hard requirements beyond the base VeloxFactory stack: a running Redis instance and the 
php-redis PHP extension. Neither is optional, Horizon will refuse to start without both.
Redis
Redis can be installed natively or run as a Docker container. Both work equally well; the choice depends on your infrastructure preferences.
Native installation:
apt install redis-server
systemctl enable redis-server
systemctl start redis-server
Docker container:
docker run -d \
  --name redis \
  --restart unless-stopped \
  -p 127.0.0.1:6379:6379 \
  redis:alpine
The container binds to 
127.0.0.1 only, Redis is not exposed to the network, which is the correct default for a single-server deployment.
Whichever method you choose, verify connectivity before proceeding:
redis-cli ping
# Expected: PONG
PHP Redis Extension
VeloxFactory is configured to use 
phpredis as the Redis client. The extension must be installed and active for PHP:
apt install php-redis
systemctl restart php8.2-fpm   # adjust version to match your PHP installation
Confirm the extension is loaded:
php -m | grep redis
# Expected: redis
.env Configuration
With Redis running and the extension installed, update your 
.env to activate Redis as the queue driver:
QUEUE_CONNECTION=redis
REDIS_CLIENT=phpredis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379
Web Server
VeloxFactory requires a web server that routes all requests through Laravel's 
public/index.php entry point. Both Apache2 and nginx are supported. The Horizon dashboard at 
/horizon and the Reverb WebSocket endpoint require no special routing rules, they are handled by Laravel and PHP-FPM like any other request, with one exception: Reverb needs a WebSocket proxy pass.
Apache2
Enable 
mod_rewrite before configuring the vhost:
a2enmod rewrite proxy proxy_http proxy_wstunnel
systemctl restart apache2
Virtual host configuration:
<VirtualHost *:80>
    ServerName veloxfactory.example.com
    DocumentRoot /var/www/veloxfactory/public
    <Directory /var/www/veloxfactory/public>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>
    # Reverb WebSocket proxy
    ProxyPreserveHost On
    ProxyPass /app ws://127.0.0.1:8080/app
    ProxyPassReverse /app ws://127.0.0.1:8080/app
    ErrorLog ${APACHE_LOG_DIR}/veloxfactory-error.log
    CustomLog ${APACHE_LOG_DIR}/veloxfactory-access.log combined
</VirtualHost>
Laravel's bundled 
.htaccess in 
public/ handles the rewrite rules, no additional configuration needed for URL routing.
nginx
server {
    listen 80;
    server_name veloxfactory.example.com;
    root /var/www/veloxfactory/public;
    index index.php;
    # Laravel URL routing
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    # PHP-FPM
    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_read_timeout 120;
    }
    # Reverb WebSocket proxy
    location /app {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $host;
    }
    # Block dotfile access
    location ~ /\.(?!well-known).* {
        deny all;
    }
}
ℹ️ Adjust the PHP-FPM socket path to match your PHP version. On systems with multiple PHP versions installed, the socket is typically at 
/var/run/php/php8.2-fpm.sock. Verify with 
ls /var/run/php/.
Queues
VeloxFactory uses three queues with distinct priorities:
  
    
      
Queue
      
Jobs
      
Notes
    
  
  
    
      
high
      
Thumbnail generation
      
Dispatched on-demand when a report is rendered. Processed with highest priority, workers on this queue are never blocked by maintenance routines.
    
    
      
default
      
Mail dispatch, the scheduler tick
      
Mails sent in background mode are queued here, together with the minute tick that looks for due schedules. Both are short jobs.
    
    
      
scheduler
      
Runs of the Job Scheduler
      
Scheduled renders and the purge run. These are the long jobs of the instance, minutes rather than seconds, so they get a queue of their own.
    
  
ℹ️ The three queues run in separate worker pools. A purge run on the 
scheduler queue cannot delay thumbnail generation on 
high or a mail on 
default, they never compete for the same worker.
Mail Dispatch
A mailing sent with 
sendAsync creates its mail task immediately and hands the send to the 
default queue. The job carries only the ID of the task, never the attachments, so nothing large ever travels through Redis: the files are read from the history disk at send time.
A mail that runs into the dispatch rate limit of its mailer is not failed and not lost. The job is released back onto the queue with a delay until the next window opens, and the task stays pending in the meantime. Several workers may try to send at the same time, the limiter counts atomically in Redis, so the configured caps hold regardless of how many workers are running.
Scheduled Work
Every recurring job of the instance is a record in the Job Scheduler, with its own crontab expression. Laravel's own schedule holds exactly one entry: once a minute it queues 
DispatchDueScheduledJobsJob, which reads the due schedules from the database and queues one run per schedule on the 
scheduler queue.
That includes the purge run, which deletes print tasks, mail tasks, history records, orphaned files and the scheduler's own run log in one pass and in a fixed order. The Schedule your jobs chapter covers the retentions and the rest of the configuration.
A scheduled run is attempted once and is never retried: a second attempt would print a second label and send a second mail. Two runs of the same schedule never overlap either. What happened is on the run record, with its trace id.
Horizon Supervisors
Horizon manages workers through internal supervisors, process groups, each responsible for one queue. The system-level Supervisor (Supervisord) only ever manages the single Horizon master process; Horizon itself handles everything below that.
  
    
      
Supervisor
      
Queue
      
Balancing
      
Notes
    
  
  
    
      
supervisor-rendering
      
high
      
Auto
      
Scales worker processes dynamically based on queue depth, up to 10 in production. Job timeout: 120 seconds.
    
    
      
supervisor-default
      
default
      
Simple
      
Fixed worker count, up to three processes in production. Runs with lower CPU priority (
nice 10), mail dispatch should not compete with rendering for system resources. Job timeout: 300 seconds.
    
    
      
supervisor-scheduler
      
scheduler
      
Simple
      
Up to two processes, on its own queue connection 
redis-scheduler and with lower CPU priority (
nice 10). Job timeout: 1800 seconds, long enough for a purge over a large history disk or a batch of scheduled renders.
    
  
ℹ️ A connection's 
retry_after has to stay above the job timeout of every supervisor using it. A job that runs longer than 
retry_after is considered lost and handed to a second worker while the first is still working on it, which for a scheduled render means a duplicate print and a duplicate mail. The 
redis connection allows 360 seconds against a timeout of 300, 
redis-scheduler allows 1860 against 1800. Raise 
retry_after first whenever you raise a timeout.
System Supervisor Configuration
Supervisord keeps three VeloxFactory processes alive and restarts them automatically on failure: the Horizon master, the Reverb WebSocket server, and the scheduler.
; Horizon - manages all VeloxFactory queue workers internally
[program:veloxfactory-horizon]
directory=/var/www/veloxfactory
command=/usr/bin/php artisan horizon
user=www-data
process_name=%(program_name)s
numprocs=1
autostart=true
autorestart=true
startretries=10
stopasgroup=true
killasgroup=true
stopsignal=TERM
startsecs=3
stopwaitsecs=1860
redirect_stderr=true
stdout_logfile=/var/log/supervisor/veloxfactory-horizon.log
environment=HOME="/home/www-data",PATH="/usr/local/bin:/usr/bin:/bin"
; Reverb - WebSocket server for real-time events
[program:veloxfactory-reverb]
directory=/var/www/veloxfactory
command=/usr/bin/php artisan reverb:start
user=www-data
autostart=true
autorestart=true
startretries=10
stopasgroup=true
killasgroup=true
stopsignal=INT
startsecs=3
stopwaitsecs=60
redirect_stderr=true
stdout_logfile=/var/log/supervisor/veloxfactory-reverb.log
environment=HOME="/home/www-data",PATH="/usr/local/bin:/usr/bin:/bin"
; Scheduler - runs Laravel's task schedule every minute
[program:veloxfactory-schedule]
directory=/var/www/veloxfactory
command=/usr/bin/php artisan schedule:work
user=www-data
autostart=true
autorestart=true
startretries=10
stopasgroup=true
killasgroup=true
stopsignal=INT
startsecs=3
stopwaitsecs=60
redirect_stderr=true
stdout_logfile=/var/log/supervisor/veloxfactory-schedule.log
environment=HOME="/home/www-data",PATH="/usr/local/bin:/usr/bin:/bin"
ℹ️ 
stopsignal=TERM is required for Horizon. SIGTERM triggers a graceful shutdown, Horizon finishes any in-flight jobs before stopping its workers. Using SIGKILL or SIGINT instead will interrupt running jobs mid-execution and may leave Report History Records in an incomplete state.
The scheduler process drives every recurring job of the instance. Without 
schedule:work running (or an equivalent cron entry calling 
schedule:run every minute), no schedule fires: no scheduled render, no cleanup, and the disk keeps filling. A cron entry is the alternative on hosts without Supervisord:
* * * * * cd /var/www/veloxfactory && php artisan schedule:run >> /dev/null 2>&1
After updating the configuration:
supervisorctl reread
supervisorctl update
supervisorctl status
The Dashboard
The Horizon dashboard is available at 
/horizon. It is restricted to users with the 
global:admin permission, the same permission required to manage users and system-wide settings.
The dashboard provides a real-time view of the entire queue system: pending and completed jobs, throughput metrics, worker counts per supervisor, and a full log of failed jobs with their stack traces. Failed jobs can be retried directly from the dashboard without any CLI access.
For scheduled work the Job Scheduler's own run log is the better place to look: it holds one record per run with its trace id, its result and the history record it produced. Horizon shows the job, the run log shows what the job did.
Graceful Shutdown & Deployments
When Horizon is stopped, for deployments, configuration changes, or server maintenance, it finishes any jobs currently in flight before exiting. The Supervisord configuration allows up to 1860 seconds for this drain, matching the longest job timeout of any supervisor, so even a purge run over a large history disk finishes cleanly.
# Stop Horizon gracefully (in-flight jobs will finish first)
supervisorctl stop veloxfactory-horizon
# Restart after a deployment
supervisorctl restart veloxfactory-horizon
Never force-kill the Horizon process during a deployment. Always use 
supervisorctl stop or 
supervisorctl restart, both send SIGTERM and wait for the drain period.
A deployment window shorter than the drain period is worth planning around the schedules: a restart during the nightly purge waits for it, and a schedule whose slot falls into the downtime is dropped rather than fired late.

Integrations
Connecting VeloxFactory to other systems and to AI assistants.

AI MCP Server
VeloxFactory can be operated directly through an AI assistant. A dedicated MCP Server, available as an add-on for VeloxFactory customers, exposes report configs, rendering, print dispatching, mailing, recurring jobs and user administration through the Model Context Protocol (MCP), so any MCP-compatible AI assistant can manage VeloxFactory through plain conversation instead of the frontend or hand-written API calls.
💬 In short: if you can describe the task, your assistant can do it. No API documentation to read, no frontend clicks to remember, and not tied to any single AI provider.
What It Lets You Do
The MCP Server gives your assistant access to everything VeloxFactory can do, organised into a few practical areas.
Manage reports by talking, not clicking. Create, update, and organise report configs, connection configs, and report contexts through conversation. "Clone the KanBan label as a QA version and rename the fields" is a request your assistant can carry out directly.
Render and preview on demand. Ask for any report to be rendered with real or example data, and get a finished PDF back, opened automatically, ready to view. No need to log into the frontend or assemble an API request by hand. This includes swapping an image in on the fly for a single render, a file from the instance's resources folder, an 
https:// URL, or a Base64 upload, without editing the report configuration itself.
Handle files without the round-trip. Uploading a new 
.jrxml template, swapping a logo, or attaching a resource image is as simple as pointing your assistant at the file on your computer. It takes care of the technical side.
Dispatch print jobs. Have a rendered document sent straight to a print task, check its status, or mark it as printed, the same dispatching VeloxFactory already does, just requested in a sentence. Printers can be named the way people name them: VeloxFactory resolves a display name such as Warehouse Label 01 to the queue name of the print server and fills in the broadcast channel by itself, so the assistant never has to look a printer up first.
Maintain the printer master data. List, create, update, retire, or delete the printers your company prints on, including location, type and broadcast ID, so the pickers in the frontend and every print task stay in sync with reality.
Send a rendering by mail. A render can go out as a mail in the same request, with the PDF and an optional xlsx attached. Mailers and mail templates are referenced by name, so "render the delivery note for order 4711 and mail it to dispatch" is one message. The assistant can also set the mail side up from scratch: create an SMTP account from a provider's documented settings, send a test mail to prove the credentials, write a template against the real placeholder catalogue of a specific report, and preview it before anyone receives it. A document that was rendered earlier can be mailed again at any time, to a freely chosen recipient.
Put recurring work on a schedule. The shift report that belongs in a mailbox at six every morning does not need anyone to ask for it. The assistant can turn a sentence into a schedule, confirm the crontab expression by reading the next run times back, run the schedule once by hand to check it, and only then switch it on. A schedule can just as well be pointed at a single date and time instead of a crontab expression, firing exactly once and, if wanted, deactivating itself afterwards. The cleanup schedule that keeps history, print tasks, mail tasks and files from growing without bound is maintained the same way, one retention at a time.
Administer users and access. Create accounts, adjust permissions, reset passwords and enable or disable access. Day-to-day administration happens in conversation instead of in the interface.
Keep track of history. Pull up past renderings, review what was generated when and by whom, follow a trace id from a scheduled run through to the mail it produced, and clean up records that are no longer needed.
At a Glance
Coverage is complete, every part of VeloxFactory is reachable, not just the rendering side:
  
    
      
Area
      
What's covered
    
  
  
    
      
Users
      
List, view, create and update accounts; change passwords; enable and disable access
    
    
      
Report Contexts
      
List, view, create, update, and delete
    
    
      
Connection Configs
      
List, view, create, update, delete, and test a database connection
    
    
      
Common Report Resources
      
List, view, create, update, and delete (logos, images, shared files)
    
    
      
Report Configs
      
List, view, create, update, delete, manage resources/parameters/fields, generate previews, and render (including per-render image overrides via 
resourceOverrides and an optional 
mailing segment)
    
    
      
Report Resources
      
Link or unlink a Common Report Resource to a report
    
    
      
History Records
      
List, view, create, update, delete, print, mail again, and clean up linked print tasks
    
    
      
Print Tasks
      
List, view, create, update, delete, and set status/printed state
    
    
      
Printers
      
List, view, create, update, and delete printer master data; names are resolved automatically when a print task is dispatched
    
    
      
Mailers
      
List, view, create, update, and delete SMTP accounts, and send a test mail to prove the credentials
    
    
      
Mail Templates
      
List, view, create, update, and delete; read the placeholder catalogue of a report, and preview subject and body without sending anything
    
    
      
Mail Queue
      
List and view mail tasks, mail an existing rendering, create a task directly, repeat one with corrected recipients, and delete
    
    
      
Scheduled Jobs
      
List, view, create, update, and delete schedules; validate a crontab expression and preview its next run times; set a schedule to run once at a given date and time instead of recurring; read the placeholders a schedule may use; run one immediately; adjust the retentions of the cleanup schedule
    
    
      
Run Log
      
List and view the runs of a schedule, searchable by trace id and outcome, and delete single entries
    
    
      
Local Utilities
      
Automatically open rendered PDFs, URLs, and output folders on your machine
    
  
89 tools in total, covering the full VeloxFactory API.
ℹ️ API tokens are not part of the tool set. They are issued and revoked in the web interface only. The MCP server talks to VeloxFactory with a token of its own, and a request authenticated that way cannot manage tokens. Asked for a token, the assistant points at Users → user → API Tokens instead.
What This Looks Like in Practice
A few examples of the kind of request the MCP Server is built for:
"Render the A5 KanBan label for article 4561287-154 and show me the PDF."
"I designed a new label in Jaspersoft Studio, onboard it as a report config."
"Create a new user for our warehouse lead with admin rights."
"Print this delivery note to the shop floor printer and let me know once it's done."
"Show me every report config connected to the QA database."
"Render this label but use this product photo instead of the linked one, just for this one print."
"Add the new label printer in hall 2 and send the next delivery note there."
"Mail this morning's shift report to the supervisor again, this time with the Excel export."
"Set up our Office 365 account as a mailer and send a test mail to check it works."
"Send the weekly stock list to disposition every Monday at six, and tell me the next three times it would run."
"Run the year-end archive job once on New Year's Eve at midnight and turn the schedule off afterwards."
"Which scheduled runs failed last night, and what did they say?"
Each of these would otherwise mean a frontend session or a small API script. With the MCP Server, they are a single message.
Built-In Know-How
Access to the tools is only half the story. Alongside the MCP Server, kiwi software also provides a companion Skill, a packaged layer of accumulated know-how that teaches the assistant how to use those tools well, not just that they exist.
In practice, this is what separates "the assistant can technically call the API" from "the assistant makes the same good judgment calls a person who knows VeloxFactory inside out would make": choosing the right output format for the situation, batching multiple renders sensibly instead of opening five windows in a row, staying within an instance's rate limit, and following VeloxFactory's own conventions rather than generic assumptions.
It also covers the judgment calls that only matter once something runs unattended: checking what a render actually reported about its mail instead of trusting a 200, and testing a schedule by hand before giving it a cron expression, so nobody finds out at three in the morning that it prints four hundred labels.
The most visible example: with the Skill in place, the assistant can design a brand-new report template from scratch (a label, delivery note, or certificate) without ever opening Jaspersoft Studio. It knows the exact conventions a 
.jrxml file needs to work in VeloxFactory (parameter naming, example values, and so on) and checks its own work with a preview before calling the template done.
💬 The Skill ships together with the MCP Server as part of the same add-on, there is nothing separate to install or configure.
Who It Is For
The MCP Server is aimed at teams that already run VeloxFactory and want a faster way to handle the routine work around it, onboarding new report templates, day-to-day administration, one-off renderings, or quick checks on what has already been generated.
It is a natural fit for anyone comfortable working with an AI assistant who would rather describe a task than click through a frontend or write an API call, including teams without dedicated developer resources to spare on integration work. Since MCP is an open, provider-independent standard, it is not limited to a single AI product.
Getting It
The MCP Server is built and maintained by kiwi software as an add-on to a VeloxFactory license. It runs locally alongside your MCP-compatible AI assistant (Claude being one example) and connects to your VeloxFactory instance using your own API credentials. Nothing about your data passes through a third party.
Setup is handled together with kiwi software as part of onboarding, typically alongside the initial VeloxFactory rollout or added to an existing installation.
ℹ️ Interested? Reach out via the Get VeloxFactory page, or try the live demo first at demo.veloxfactory.dev.

Project Examples
Typical VeloxFactory use cases from real-world projects.

Article Label Printing at Scale
Overview
A trading company with its own in-house logistics operation needed a fast, reliable way to generate article labels directly from their ERP data. Manual label creation had become a bottleneck as order volumes grew, and the team was looking for a solution that would integrate cleanly with their existing infrastructure without adding complexity.
Together with kiwi software, they rolled out VeloxFactory as the rendering engine behind a lean scanning workflow that now produces over 4,000 labels per day, fully automated and delivered straight to the warehouse floor.
The Challenge
Warehouse staff had been looking up article data manually, copying it into label templates, and printing. As the business grew, this process couldn't keep up. What they needed was simple:
Labels generated in under a second per scan
Data pulled directly from the ERP, no manual input
An interface that works with a standard barcode scanner, no keyboard required
No additional middleware, no fat clients, no complex integrations
The Solution
kiwi software built a lightweight single-page scanning mask that ties directly into VeloxFactory's REST API. The whole frontend was finished in a single day. The workflow is straightforward:
A warehouse employee scans an article barcode
The scanning mask sends one API request to VeloxFactory, passing only the article number
VeloxFactory fetches all relevant article data in real time from the connected MS SQL database
The Jaspersoft report template is rendered with the live data and output as a print-ready PDF
VeloxFactory dispatches the label to the company's print server, which routes it to the nearest floor printer
Scan in, label out. Typically within 800 ms end-to-end.
Technical Setup
Component
Details
Frontend
Custom scanning mask (developed by kiwi software)
Report engine
VeloxFactory
Report template
Jaspersoft Studio (.jrxml), designed to label specs
Data source
MS SQL Server via VeloxFactory data adapter (sqlsrv driver)
API input
Article number only
Print delivery
VeloxFactory Print Task to on-premises print server
Daily volume
4,000+ labels
The data adapter resolves the article number into the full set of label attributes: description, unit, weight class, hazard indicators and storage zone. The report template then lays these out according to the company's label specification.
Results
Since going live, the process runs without any manual intervention:
4,000+ labels generated and printed per day, fully automated
Label generation time down from several minutes to under one second
Data entry errors eliminated completely
Staff need no training beyond a single walkthrough of the scanning mask
No local print drivers or client software required on scanning stations
Why VeloxFactory
The combination of a clean REST API, native data adapter support and built-in print server integration meant there was no need for a separate middleware layer or custom rendering pipeline. kiwi software connected the MS SQL database via the sqlsrv driver, configured the print server target and had the scanning frontend running in a day.
"We connected the database, set up the print target and had a working frontend the same day."
-- kiwi software, project lead

Bill of Materials Generation
Overview
A manufacturing company needed a simple, reliable way to get printed bills of materials into the hands of their foremen at the start of each production run. Their existing process involved exporting data manually from their production system, which was slow and prone to errors when order volumes picked up.
By connecting VeloxFactory to their MySQL production database, they now generate 200 to 300 bills of materials per day, each one triggered with nothing more than a production order reference number.
The Challenge
Before VeloxFactory, generating a bill of materials meant pulling data out of the production system by hand, formatting it and sending it to print. The foreman often had to wait, and mistakes in the data transfer occasionally caused issues on the shop floor. The company needed:
A fast way to generate accurate, print-ready BOMs from live production data
A process simple enough for office staff to use without training
No dependency on exports or manual data handling
The Solution
kiwi software connected VeloxFactory to the company's MySQL production database using a configured data adapter. Staff now use VeloxFactory's built-in web frontend to trigger BOM generation: they type in the reference number of a production order, VeloxFactory fetches the full set of production data from the database and renders a structured bill of materials as a PDF. The document is printed and handed to the foreman before the run starts.
No exports, no formatting, no waiting.
Technical Setup
Component
Details
Frontend
VeloxFactory web frontend (built-in)
Report engine
VeloxFactory
Report template
Jaspersoft Studio (.jrxml)
Data source
MySQL database via VeloxFactory data adapter
API input
Production order reference number
Output
Print-ready PDF bill of materials
Daily volume
200 to 300 BOMs
The data adapter resolves the production order reference into the full component list, quantities, units and any production notes required for the BOM layout.
Results
Since the rollout, BOM generation is no longer a bottleneck before production starts:
200 to 300 bills of materials generated per day
Generation time reduced from several minutes to seconds
No more manual data exports or formatting steps
Foremen receive accurate, consistently formatted documents every time
Why VeloxFactory
VeloxFactory's built-in web frontend meant no custom tooling was needed at all on the user side. kiwi software set up the MySQL data adapter and the Jaspersoft report template, and the company was up and running within a day. The foremen now get a clean, standardised BOM for every production order without anyone having to touch the underlying data.
"Our foremen get the BOM before the run starts. That used to take minutes, now it takes seconds."
-- Production manager