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

VeloxFactory is a web application that lets you manage and render JasperReports templates - via a clean frontend, a powerful REST API, or both. It turns the well-established JasperReports engine into something any application can consume with a single HTTP call.

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 sits on top of the JasperReports render engine and exposes its capabilities via a clean REST API and a management frontend. The render engine runs in pure PHP - no JVM process required on your application server. 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.

The setup is intentionally slim. PHP, a database for VeloxFactory itself, and the JasperPHP render engine, that is the stack. No application server, no JVM process to manage, no separate Jaspersoft infrastructure. VeloxFactory bundles everything it needs.

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.

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

Bundled Dependencies

The following components are bundled with VeloxFactory, no separate installation required:

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.

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.

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.

Every ReportConfig requires a context. A single context can be shared across any number of report configurations.

ReportConnectionConfig

A connection config represents a live database connection that VeloxFactory can use as a data source when rendering a report. When assigned to a ReportConfig, VeloxFactory executes the report's SQL query against this connection at render time and feeds the result rows into the report as field data.

Supported drivers:

Connection status is derived from connection_tested:

Network Requirements

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

When is a ReportConnectionConfig needed?

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

ReportConfig

The ReportConfig is the core entity of VeloxFactory. It represents a single JasperReports template (the .jrxml file) together with all the metadata VeloxFactory maintains about it.

When a .jrxml file is uploaded, VeloxFactory automatically analyses it and creates the associated ReportParameter, ReportField, and ReportResource records. You then review and complete the auto-generated data, for example setting example values or uploading resource files.

ReportParameter

Parameters are the inputs passed into a report at render time: dates, IDs, filter values, flags, and so on.

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

Three parameter name prefixes carry meaning beyond the render itself:

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

ReportField

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

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

ReportResource

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

A ReportResource either holds its own uploaded file or it is linked to a CommonReportResource, never both at the same time. When linking to a common resource, the resource's own file is deleted and the common file is used in its place.

CommonReportResource

A CommonReportResource is a shared graphic asset (a company logo, a standard header image) that multiple report configurations can reference. Instead of uploading the same file to each report individually, you upload it once and link individual ReportResource records to it.

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

ReportHistoryRecord

A ReportHistoryRecord captures the full context of a rendering: what was requested, what was returned, and whether it succeeded. Creating a history record is optional and controlled by the createHistoryRecord flag in the render request.

Output types (output_type):

Status values (status):

History records are retained for a configurable number of days, set as a retention on the Purge Job. Thumbnails are generated asynchronously after rendering completes. Deleting a history record removes its PDF and its xlsx from disk together with the record.

ReportPrintTask

A ReportPrintTask represents a print job dispatched to a physical printer. It is always linked to a ReportHistoryRecord, you always print a specific past rendering, not a report config directly.

Status values (status):

Printer

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

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

Mailer

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

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

MailTemplate

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

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

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

ReportMailTask

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

Status values (status):

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.

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

ScheduledJobRun

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

Status values (status):

Audit Trail

Every model in VeloxFactory tracks who created and last updated a record, and which API token was used. This information is available on all records via the withAudit=true query parameter in the API.

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

Environment Configuration

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

Application

Queue & Redis

Horizon

Job Scheduler

Mailing

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

Retention & Purge

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

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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

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:

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:

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:

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.

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.

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

Tokens are created and managed per user, either from the user management section in the frontend, or via the API itself (POST /api/v1/user/{id}/create-token). Each token can be revoked at any time. 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.

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.

Response Structure

All API responses follow a consistent envelope format.

Success:

{
  "success": true,
  "count": 1,
  "data": { ... },
  "meta": [],
  "status": 200
}

Error:

{
  "success": false,
  "errors": ["Descriptive error message"],
  "meta": {},
  "status": 404
}

The count field reflects the number of records in data, 1 for single-record responses, the actual number of returned records for collections. The meta field carries contextual information such as the traceId of a render run.

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.

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

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

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
  },
  "meta": {
    "traceId": "a3f9c1d2-4e87-4b2a-9f1c-d3e8b7a20f61"
  },
  "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.

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.

Access

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.

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.

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.

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.

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.

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.

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

Interested in using VeloxFactory in your own environment? Get in touch, we'll figure out the right setup together.

Contact

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:

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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 JasperReports. 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>

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.
• The report previews correctly in Jaspersoft Studio using the local data adapter — this confirms the layout and expressions are valid before upload.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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

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.

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.

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.

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.

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.

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
}

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

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.

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.

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.

The three modes:

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.

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:

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.

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.

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.

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.

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.

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

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:

Base64 example:

{
  "outputType": "base64",
  "resourceOverrides": {
    "P_RESOURCE_ASSEMBLY_IMAGE": {
      "base64": "iVBORw0KGgoAAAANSUhEUgAA...",
      "fileName": "part-4471.png"
    }
  },
  "createHistoryRecord": false,
  "createPrintTask": false
}

{
  "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
}

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.

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
}

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.

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
    }
  },
  "meta": [],
  "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..."
    }
  },
  "meta": [],
  "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.

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.

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.

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.

• 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?

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.

How It Works

1. Open Scan2Print from the main navigation.
2. 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.
3. The page now shows one input field per scan parameter of the report, stacked on top of each other.
4. 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.
5. 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:

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:

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.

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:

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.

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

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.

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.

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.

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.

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.

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

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.

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

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:

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.

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.

VeloxFactory does not talk to printers directly. Instead, a lightweight companion application, the Background Printing Service, runs on any Windows machine that has the target printers installed. It receives print tasks from VeloxFactory, renders the PDF to the printer, and reports the result back. The two components communicate exclusively over the VeloxFactory API and WebSocket; there is no shared database or filesystem.

How it works

The service starts as a regular Windows console process and works through two sequential phases.

Phase 1 - Initial pull

On startup the service immediately calls GET /api/v1/report-print-task?status=pending and processes all tasks it finds. It repeats this in a loop, waiting two seconds between rounds, until the queue comes back empty and no jobs are still running. This ensures that any tasks queued while the service was offline are handled before switching to real-time mode.

Phase 2 - WebSocket listener

Once the initial queue is drained, the service connects to VeloxFactory's WebSocket endpoint (Laravel Reverb) and subscribes to the private channel private-report-print-tasks. From this point on, it reacts to incoming events in real time. If the WebSocket connection drops for any reason, the service waits five seconds and reconnects automatically, no manual restart required.

Processing a print task

Whether a task arrives via the initial pull or via a WebSocket event, the processing steps are identical:

1. Fetch: The service calls GET /api/v1/report-print-task/{id} to retrieve the full task record, including the PDF as a Base64 string.
2. Write temp file: The PDF is decoded and written to a temporary file in reportPdfFileTempPath (e.g. C:\VeloxFactory\temp\42_delivery_note.pdf).
3. Print: PdfiumViewer opens the PDF and sends it to the printer specified in printerName. The print is repeated numberOfCopies times.
4. Report back: On success, the service calls PATCH /api/v1/report-print-task/{id}/set-printed, which sets the status to printed. On failure, it calls PATCH /api/v1/report-print-task/{id}/set-status with {"status": "error", "errorMessage": "..."}.
5. Cleanup: The temporary file is deleted regardless of the outcome.

Broadcast ID filtering

listeningBroadcastIds is a list of broadcast channel identifiers the service will accept. Any report-print-task.created event whose broadcastId is not in this list is silently ignored.

This makes it straightforward to run multiple service instances in parallel, for example one per location or printer group, each configured to respond only to its own broadcastId. The initial pull is not filtered this way: it always processes all pending tasks returned by the API, regardless of broadcastId.

Configuration

All settings live in App.config in the applicationSettings section. Edit the file in a text editor and restart the service for changes to take effect.

Concurrency

The service uses two layers of concurrency control to avoid overloading printers.

A global semaphore limits the total number of tasks being processed at the same time to maxParallelPrintJobs. In addition, a per-printer semaphore ensures that only one print job runs on a given printer at a time, jobs targeting different printers can execute in parallel, but two jobs targeting the same printer are always serialised. This prevents the spooler from receiving multiple jobs simultaneously from the service.

Logging

The service uses Serilog and writes to both the console and a rolling log file. Log files are capped at 100 MB each; up to 10 rotated files are retained before the oldest is deleted.

Set laconicLogging to True in App.config to suppress informational messages and log only errors, useful in production once the service is confirmed working.

Dependencies

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.

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

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:

1. The name is compared to the queue name of every printer record, ignoring upper and lower case.
2. If nothing matches, it is compared to the display name.
3. 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.
4. If nothing matches, the name is stored exactly as supplied.

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.

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.

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.

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.

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

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.

The three parts

Mailing is built from three things you configure once and one thing you send per render.

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.

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:

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.

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.

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.

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.

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.

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.

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.

A render that mailed something returns the mail task in its response, and anything noteworthy about the mailing in meta.mailing:

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.

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.

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.

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

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.

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:

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:

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.

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.

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.

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.

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.

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.

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.

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.

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.

Whitelabeling

By default every mail looks the same: a card in the colours of your VeloxFactory installation, read straight from the application's stylesheet, with a coloured header bar and a footer. 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:

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.

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.

Uploading the graphics a template uses is a separate permission, common-report-resource:create and :update, because those files are shared with the reports.

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

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.

Two kinds of schedule

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.

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.

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.

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.

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.

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.

What has to be running

The Job Scheduler depends on the two background processes VeloxFactory runs in production.

Both belong under Supervisor in production. The Administration chapter has the details.

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.

What you configure

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.

Output types

A schedule offers three of the four output types.

preview is refused. A preview render deletes its own file again, so unattended it would produce nothing at all.

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.

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.

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.

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.

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.

The five steps

Saying how long

Every step has its own retention in days, and every step can be switched off on its own.

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.

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.

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.

What customers built with VeloxFactory, and what it replaced.

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:

1. 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
2. For each article, it detects the packaging levels present: individual packaging, outer carton and master carton
3. 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
4. For each packaging level, it calls VeloxFactory four times: declaration of conformity and technical documentation, each in German and English
5. The PDFs are filed on the document drive; any previous version is moved to a dated archive folder
6. The ERP receives a timestamp on the article, so it is only processed again when relevant data changes
7. 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

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.

Running an instance: background processes, queues and maintenance.

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;
    }
}

Queues

VeloxFactory uses three queues with distinct priorities:

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.

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"

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.

Connecting VeloxFactory to other systems and to AI assistants.

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.

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, or issue API tokens for new integrations, day-to-day administration handled conversationally.

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:

91 tools in total, covering the full VeloxFactory API.

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.

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.

Typical VeloxFactory use cases from real-world projects.

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:

1. A warehouse employee scans an article barcode
2. The scanning mask sends one API request to VeloxFactory, passing only the article number
3. VeloxFactory fetches all relevant article data in real time from the connected MS SQL database
4. The Jaspersoft report template is rendered with the live data and output as a print-ready PDF
5. 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

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

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

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