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

VeloxFactory takes the JasperReports template format, JRXML, and puts a lightweight render engine of its own underneath it. The templates you already know, designed in Jaspersoft Studio as before, run on a slim, modern stack, render fast, and are one HTTP call away from a finished report. Around that engine sits a web application to manage and render them - via a clean frontend, a powerful REST API, or both.

Where VeloxFactory Fits

JasperReports is a mature, battle-tested report engine. It produces high-quality PDFs, supports complex layouts, barcodes, images, and dynamic data - and it has been doing so reliably for decades. Integrating it directly requires a JVM on your server and Java code to drive it - which is a natural fit for Java stacks, but an overhead most PHP, Python, or C# teams prefer to avoid.

VeloxFactory keeps the template format and replaces what runs beneath it. Its render engine is lightweight and runs in pure PHP - no JVM process required on your application server - and its capabilities are exposed via a clean REST API and a management frontend. You design your report templates in Jaspersoft Studio as usual, upload them once, and from that point on, rendering is just a POST request.

POST /api/v1/report-config/A5_KanBan/render
Content-Type: application/json
Authorization: Bearer <token>

{
  "outputType": "base64",
  "parameters": { "P_ARTICLE_NUMBER": "4561287-154" },
  "data": [...],
  "createHistoryRecord": true
}

That is the entire integration.

Where It Came From

VeloxFactory was built by someone with a logistics and IT background who needed a simple, reliable way to generate article labels on demand - from whatever system was running at the time, without caring about the underlying report engine. The original idea was modest: a small API wrapper around JasperReports, nothing more.

It grew. A frontend to manage templates. Connection configs for live SQL data. History records for traceability. Print task dispatching, printer master data, a scan station. Mail delivery with its own mailers, templates and dispatch queue. A job scheduler, so the recurring work runs itself. A permission system. What started as "just get me a label PDF" is now a full suite, capable of enterprise integration on demand.

What VeloxFactory Does

At its core, VeloxFactory does six things:

Manages report templates. You upload .jrxml files, and VeloxFactory analyses them automatically, detecting parameters, data fields, and image resources. Everything is stored, versioned, and ready to render.

Connects to your data. VeloxFactory can execute SQL queries against live databases at render time. MySQL, MariaDB, PostgreSQL, and SQL Server are all supported. No live connection needed either - you can deliver data directly in the render request as a JSON array, which makes it equally useful for applications that already have the data in memory.

Renders on demand. A single API call produces a PDF. You choose the output format - Base64-encoded inline, a file URL, or silent output for print-only flows. Rendering is synchronous and fast.

Dispatches print jobs. Rendered PDFs can be forwarded directly to a print service via WebSocket, creating a traceable ReportPrintTask with status tracking. Labels off the printer, not just on the screen. Printers are maintained as master data and picked by name, and with Scan2Print a barcode scan on a phone or a handheld is enough to turn a scanned value into a printed label.

Delivers by mail. A rendering can be sent straight to whoever needs it. A render request carries an optional mailing segment, and VeloxFactory sends an HTML mail through a configured mailer, using a configured template, with the PDF attached and, on request, an xlsx export of the same data. Sending is synchronous or queued, every mail is logged as a traceable ReportMailTask.

Works on a schedule. Not every document has somebody waiting for it. The shift report that belongs in a mailbox at six in the morning, the weekly stock list, the cleanup that keeps the history from growing without bound: recurring work is configured as a schedule with a crontab expression, maintained in the frontend or through the API like everything else. A scheduled render is a complete render request, printing and mailing included, and every run is logged with its trace id.

Who It Is For

VeloxFactory is for anyone who needs to generate documents - labels, reports, delivery notes, production sheets, certificates - reliably and programmatically. The typical home is in logistics, production, and warehousing, where printing article labels, kanban cards, or shipment documents is a daily operational need and downtime is not an option.

More broadly: if your application needs to produce a PDF from structured data, and you do not want to build and maintain a report engine yourself, VeloxFactory is the answer.

Deployment

VeloxFactory is a standard Laravel application. It runs wherever PHP runs, which is nearly everywhere.

The setup is intentionally slim. PHP 8.2 or newer, a MySQL or MariaDB database for VeloxFactory itself, and Redis for the queue that carries thumbnails, background mails and scheduled jobs, that is the stack. Two small helpers complete it: poppler-utils draws the report thumbnails, and Supervisor keeps the background processes running. The render engine and every other library come with the application and are installed by Composer. No application server, no JVM process to manage, no separate Jaspersoft infrastructure. The complete list is on Installing VeloxFactory.

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.

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

• 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

• Create a new token and copy it immediately after generation (it is only shown once)
• Revoke any existing token with immediate effect
• Reset another user's password, or change your own after confirming the current one

• count is the number of records in data: the records on the current page for a list, 1 for a single record.
• links point to the first, last, previous and next page. A link that does not exist is null. Responses that are not paginated have all four links null.
• meta.pagination describes the page, see Pagination. A response that is not paginated reports exactly one page.
• meta carries further contextual information next to pagination, such as the traceId of a render run or the mailing result.

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 the render engine. Whether that data comes from an SQL query executed against a ReportConnectionConfig or from a data array in the API request, VeloxFactory always handles the data handoff itself.

You still benefit from configuring a data adapter in Jaspersoft Studio during development — it lets you see a realistic preview while designing the layout. Just be aware that the adapter configuration stays local to your machine.

Annotated Example

The following is a complete, minimal .jrxml that demonstrates everything discussed on this page. It is the actual A5_KanBan report included in the VeloxFactory demo. Inline comments explain each relevant element.

<?xml version="1.0" encoding="UTF-8"?>
<!-- Created with Jaspersoft Studio version 6.21.5 -->

<jasperReport
    xmlns="http://jasperreports.sourceforge.net/jasperreports"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="..."

    name="A5_KanBan"         <!-- Report Name — becomes report_name in VeloxFactory. Must be unique. -->
    pageWidth="595"          <!-- Page dimensions in Jasper pixels (1px = 1/72 inch).              -->
    pageHeight="842"         <!-- VeloxFactory converts these to mm on upload.                       -->
    ...>

    <!-- ═══════════════════════════════════════════════════════════════════
         RESOURCE PARAMETER
         Name starts with P_RESOURCE_ and class is java.lang.String.
         VeloxFactory detects this as a resource (image/logo), not a parameter.
         The defaultValueExpression points to a local file for Studio preview —
         VeloxFactory replaces it at render time with the uploaded file path.
         ═══════════════════════════════════════════════════════════════════ -->
    <parameter name="P_RESOURCE_LOGO" class="java.lang.String">
        <defaultValueExpression><![CDATA["C:/VeloxFactory/Logo_Dark.png"]]></defaultValueExpression>
    </parameter>

    <!-- ═══════════════════════════════════════════════════════════════════
         REGULAR PARAMETER
         P_ARTICLE_NUMBER is a user-supplied input value passed at render time.
         exampleValue  → used for preview rendering and pre-fills the frontend form.
         required      → omitting this parameter in a render request will cause a 422 error.
         ═══════════════════════════════════════════════════════════════════ -->
    <parameter name="P_ARTICLE_NUMBER" class="java.lang.String">
        <property name="exampleValue" value="4561287-154"/>
        <property name="required"     value="true"/>
    </parameter>

    <!-- ═══════════════════════════════════════════════════════════════════
         QUERY STRING — leave empty.
         The SQL query is defined in VeloxFactory, not here.
         ═══════════════════════════════════════════════════════════════════ -->
    <queryString>
        <![CDATA[]]>
    </queryString>

    <!-- ═══════════════════════════════════════════════════════════════════
         FIELDS
         Each field maps to a column in the SQL result or a key in the data array.
         exampleValue → used for preview rendering when no live data is available.
         ═══════════════════════════════════════════════════════════════════ -->
    <field name="articleNumber" class="java.lang.String">
        <property name="exampleValue" value="1868745-584"/>
    </field>

    <field name="description" class="java.lang.String">
        <property name="exampleValue" value="Packing Carton Size 1 - 200x150x50mm"/>
    </field>

    <field name="moq" class="java.lang.Integer">
        <property name="exampleValue" value="250"/>
    </field>

    <field name="deliveryTime" class="java.lang.String">
        <property name="exampleValue" value="3 Days"/>
    </field>

    <field name="supplier" class="java.lang.String">
        <property name="exampleValue" value="Ninghao Packaging"/>
    </field>

    <field name="barcode" class="java.lang.String">
        <property name="exampleValue" value="5698532145712"/>
    </field>

    <!-- ═══════════════════════════════════════════════════════════════════
         DETAIL BAND
         The repeating section — one iteration per data row.
         Must contain at least one <textField> using a $F{...} expression,
         otherwise VeloxFactory rejects the file on upload.
         The image element uses $P{P_RESOURCE_LOGO} — VeloxFactory resolves
         this to the uploaded resource file at render time.
         ═══════════════════════════════════════════════════════════════════ -->
    <detail>
        <band height="167" splitType="Stretch">

            <!-- Field values referenced via $F{...} expressions -->
            <textField>
                <textFieldExpression><![CDATA[$F{articleNumber}]]></textFieldExpression>
            </textField>

            <textField>
                <textFieldExpression><![CDATA[$F{description}]]></textFieldExpression>
            </textField>

            <!-- Resource image: bound to the P_RESOURCE_LOGO parameter -->
            <image>
                <imageExpression><![CDATA[$P{P_RESOURCE_LOGO}]]></imageExpression>
            </image>

        </band>
    </detail>

</jasperReport>

Pre-Upload Checklist

Before uploading a .jrxml to VeloxFactory, verify the following:

• The Report Name (name attribute on <jasperReport>) is set, descriptive, and unique.
• All resource parameters follow the P_RESOURCE_ naming convention and have class java.lang.String.
• All regular parameters have exampleValue and required custom properties set where applicable.
• All fields have an exampleValue custom property set.
• The <queryString> is empty — the SQL is managed in VeloxFactory.
• If the report has a detail band, it contains at least one <textField> with a $F{...} expression.
• Every band has splitType="Stretch", including an explicit empty <background> band, and the bands follow the JasperReports XSD order (pageFooter and lastPageFooter before summary).
• The template only uses features listed in Render engine: supported features and expressions (no charts, no crosstabs, no $R{...}).
• The report previews correctly in Jaspersoft Studio using the local data adapter — this confirms the layout and expressions are valid before upload.
• After the upload, render it once in VeloxFactory with realistic data, including enough rows for more than one page. The rendering in VeloxFactory is the reference, not the Studio preview.

VeloxFactory renders .jrxml templates with its own render engine: a pure-PHP implementation of JasperReports, based on the open source project JasperPHP and maintained by us as an independent fork. It needs no Java runtime, but it implements a defined subset of JasperReports rather than the full Java engine. This page lists exactly what that subset is, so you can design templates in Jaspersoft Studio that render the same way in VeloxFactory.

How to set up parameters, fields, resources and the query is described in Creating reports in Jaspersoft Studio. This page covers what happens inside the template: bands, elements, styles, expressions and formatting.

Two rules for every template

• Every band needs splitType="Stretch", including an explicit empty <background><band splitType="Stretch"/></background>.
• Bands must follow the JasperReports XSD order: background, title, pageHeader, columnHeader, detail, columnFooter, pageFooter, lastPageFooter, summary. Jaspersoft Studio refuses to open a file with a different order.

Bands

Elements

Every element respects printWhenExpression, evaluated for each row.

Layout rules

• StretchHeight makes the band taller, never the elements beside it. The next band starts below the lowest stretched field.
• Vertical alignment with StretchHeight: if the text fits into the field, Top, Middle and Bottom apply as usual. Only overflowing text grows downwards from the top.
• positionType="Float" moves an element down by the growth of the stretched fields above it. All other elements keep their position.
• ScaleFont reduces the font size until the text fits into the box. Line breaks are allowed.
• Page breaks fill the page down to the page footer. The decision uses the declared band height.
• <box>: <pen> applies to all four sides, topPen, leftPen, bottomPen and rightPen override it. The colour falls back from the side pen to the box pen, then to forecolor, then to black. padding sets all four paddings, leftPadding etc. override it.

Defaults are the same as in JasperReports:

• Rectangle: Opaque, white background, 1 pt black border.
• Line: 1 pt. A pen width of 0 draws nothing.
• Pen colour: lineColor takes precedence over forecolor.

Styles

• Assignment: style="Name" on the reportElement. A style with isDefault="true" applies to all elements without a style of their own.
• Inheritance: <style name="Child" style="Parent">.
• Precedence: element attribute, then all matching conditional styles in order, then the style, then its parent.
• Conditional styles are evaluated again for every row, for example to colour negative quantities red or to shade every second row.

Styles carry: mode, forecolor, backcolor, horizontal and vertical text alignment (hTextAlign, vTextAlign and the older names), rotation, markup, font name, size, bold, italic, underline, strike-through, pattern, radius, image scaling and alignment, and the child elements <pen>, <box> and <paragraph>.

Expressions

Expressions are written in Java syntax, as in Jaspersoft Studio. They are evaluated by a built-in interpreter; no code is executed on the server. Expressions work in text fields, printWhenExpression, conditional styles, variables, patternExpression, hyperlinks, images, barcodes and subreport file names.

Syntax

How values behave

• + concatenates as soon as one operand is text, from left to right: 1 + 2 + "a" gives 3a, "a" + 1 + 2 gives a12.
• 7 / 2 gives 3 (integer division), 7 / 2.0 gives 3.5.
• The type comes from the declared class of the field, parameter or variable. Declare amounts as java.math.BigDecimal, java.lang.Double or java.lang.Integer; a value declared as String is concatenated instead of added.

Three deliberate differences from Java make templates more robust:

• null is concatenated as empty text (Java: "null").
• == compares values like .equals().
• Arithmetic with null returns null instead of failing.

Methods

Static calls, constants and constructors

• Text: String.valueOf, String.format([Locale,] format, ...), String.join
• Parsing: Integer.parseInt / valueOf, Long.parseLong, Double.parseDouble / valueOf, BigDecimal.valueOf, Boolean.valueOf / parseBoolean
• Math: abs, round, floor, ceil, max, min, pow, sqrt
• Constants: Boolean.TRUE / FALSE, BigDecimal.ZERO / ONE / TEN, RoundingMode.*, Locale.GERMANY, GERMAN, US, UK, ENGLISH, FRANCE, ITALY
• Constructors: new java.util.Date(), new Date(ms), new java.text.SimpleDateFormat("...", [Locale]) with .format() and .parse(), new java.text.DecimalFormat("...").format(), new BigDecimal("1.5"), new Integer(...), new String(...), new Locale("de", "DE")

Examples

"Customer: " + $P{P_CUSTOMER}
$P{P_NOTE} == null || $P{P_NOTE}.isEmpty() ? "-" : $P{P_NOTE}
$F{status}.equals("late") && $F{qty} > 0
String.format("%s / %05d", $F{order}, $F{pos})
new java.text.SimpleDateFormat("EEEE, d. MMMM yyyy", java.util.Locale.GERMAN).format($F{date})
$F{amount}.setScale(2, java.math.RoundingMode.HALF_UP)

Legacy suffixes

Two JasperPHP shortcuts still work for existing templates: $F{amount}.toString() always returns two decimals in German format (1.234,50), and $F{amount}.numberToText() spells out a number (Portuguese). For new templates, use pattern instead.

Not supported

$R{...} (resource bundles), arbitrary Java classes, lambdas and field access without a method call (.length without parentheses). A text field with an unsupported expression falls back to plain placeholder substitution, which usually shows parts of the expression in the output. A condition with an unsupported expression counts as false, so the element is hidden.

Formatting numbers and dates

• pattern / patternExpression: patternExpression takes precedence and is evaluated for each row, for example to switch the number of decimals per article.
• Numbers use Java's DecimalFormat: #,##0.00, 0.0%, 000000, #,##0.00 €, #,##0.00;(#,##0.00), 0.00E0. Rounding is HALF_EVEN as in Java; setScale rounds HALF_UP by default.
• Dates use Java's SimpleDateFormat: dd.MM.yyyy, EEEE, d. MMMM yyyy, HH:mm.
• Values that arrive as text are formatted as well when they contain a number or an ISO date (2026-05-02, 2026-05-02 14:30:00). This matters because render requests usually pass parameters as text.

Language and locale

Pass the parameter REPORT_LOCALE in the render request, for example de_DE. It controls decimal and thousands separators, month and day names, String.format and pattern. Built in are German (including de_CH), English, French, Spanish, Italian and Portuguese. Without REPORT_LOCALE, the default locale of the installation applies (English unless configured otherwise).

Variables

• Calculations: Sum, Count, Average, DistinctCount, Highest, Lowest, First, Nothing (current value). Count and Average only count values that are not null.
• Reset: resetType="Report" or "Group". Groups reset correctly even without a group header band.
• Expressions can be any supported expression, for example $F{qty} * $F{price}.
• Built in: PAGE_NUMBER and REPORT_COUNT. For "Page N of M", use two text fields: "Page " + $V{PAGE_NUMBER}, and " of " + $V{PAGE_NUMBER} with evaluationTime="Report".

Upgrading templates from earlier versions

Templates built for earlier VeloxFactory versions keep working. Check them for these changes:

• Conditions in PHP syntax (for example is_int(...), ===, and or or in printWhenExpression) now count as false, and the element is hidden. Rewrite them in Java syntax.
• Lines without <pen> are 1 pt wide instead of a hairline.
• Element attributes override the style (previously the other way round).
• Multi-page reports fit more rows per page and repeat the column header on every page.
• Workarounds are no longer needed: concatenation with +, pattern, <box> and page footers on every page now work as in Jaspersoft Studio.

Known limits

• Charts and crosstabs are not supported and render as an empty area. Use tiles, lists and aggregated groups instead.
• noData band and $R{...} are not supported.
• isBlankWhenNull="false" is ignored; null always prints as empty text.
• A band that stretches shortly before the end of a page can reach into the page footer. Leave some space above the footer on pages with long texts.

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.

The file name may contain letters, digits, dot, hyphen and underscore, must end in .jrxml and is limited to 120 characters. Directory parts are not accepted.

Completing the Configuration

After upload, the report configuration is ready but not yet fully operational. The following steps complete it:

Upload Resource Files

If the report contains image resources (detected as P_RESOURCE_ parameters), each one requires an actual file to be uploaded. VeloxFactory cannot render the report until all resource files are in place.

Alternatively, a resource can be linked to a CommonReportResource - a shared asset reused across multiple reports, such as a company logo. Linking is permanent: the resource's own file is deleted and the common file is used in its place.

A Common Report Resource serves a second purpose as well: a PNG or JPEG uploaded there can be placed into a mail template as an inline graphic, referenced by its name. The same logo therefore covers the report and the mail it is sent with. See Mail Templates.

Resource files are images: png, jpg, jpeg, gif or webp. VeloxFactory checks the actual content, not the extension, and refuses a file whose bytes are not one of those formats.

The file name is normalised before it is stored. Any directory part is dropped, inner dots become hyphens (logo.v2.png is stored as logo-v2.png), everything outside letters, digits, hyphen and underscore becomes a hyphen, and the name part is cut at 80 characters. The stored name is what the report refers to, so a renamed file shows up under its normalised name in the resource list.

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.

The host of a connection config is checked when it is saved. Loopback and link-local addresses are refused. An instance can narrow this further with OUTBOUND_HOST_ALLOWLIST, a comma separated list of the hosts that connections and mailers may point at; an empty list means everything except loopback and link-local. A failed connection test answers with a generic message, the reason is in the application log.

Writing the SQL Query

The SQL query is written and stored in VeloxFactory, not in the .jrxml. It lives on the ReportConfig record and is executed against the assigned connection at render time.

The query must return columns whose names match exactly the field names defined in the .jrxml. For a report with fields articleNumber, description, and moq, the query must alias its columns accordingly:

SELECT
    art_no          AS articleNumber,
    art_description AS description,
    min_order_qty   AS moq,
    delivery_days   AS deliveryTime,
    supplier_name   AS supplier,
    barcode
FROM articles
ORDER BY art_no ASC

Column names are case-sensitive. articleNumber and articlenumber are not the same field.

What a Report Query May Contain

A report query is a single read statement. VeloxFactory checks it when the Report Config is saved and refuses anything else:

• It must begin with SELECT or WITH.
• It must not contain a semicolon, so a second statement cannot be appended.
• It must not use constructs that read files, write files or run commands on the database server: INTO OUTFILE, INTO DUMPFILE, LOAD_FILE, LOAD DATA, BULK INSERT, OPENROWSET, OPENDATASOURCE, xp_cmdshell, sp_OACreate, pg_read_file and their relatives.
• At most 20,000 characters.

Parameters stay parameters. They are bound by the driver, never pasted into the statement, which is why a value can safely contain quotes or a semicolon.

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
    }
  },
  "links": { "first": null, "last": null, "prev": null, "next": null },
  "meta": {
    "traceId": "ec1e29de-7aca-4c59-9722-ae9edc7d24d7",
    "pagination": {
      "currentPage": 1,
      "lastPage": 1,
      "perPage": 1,
      "total": 1,
      "from": 1,
      "to": 1,
      "hasMorePages": false,
      "path": "https://your-instance/api/v1/report-config/A5_KanBan/render"
    }
  },
  "status": 200
}

Laconic Response

With laconicResponse: true, the response contains only what is needed to retrieve the PDF:

{
  "success": true,
  "count": 1,
  "data": {
    "model": "ReportRendering",
    "traceId": "555d073b-a630-4096-acd1-643b85ed5cc9",
    "output": {
      "reportPdfFileName": "8de016b5-4cf9-423a-9575-8c3155e35410.pdf",
      "reportPdfBase64":   "JVBERi0xLjQ..."
    }
  },
  "links": { "first": null, "last": null, "prev": null, "next": null },
  "meta": {
    "traceId": "555d073b-a630-4096-acd1-643b85ed5cc9",
    "pagination": {
      "currentPage": 1,
      "lastPage": 1,
      "perPage": 1,
      "total": 1,
      "from": 1,
      "to": 1,
      "hasMorePages": false,
      "path": "https://your-instance/api/v1/report-config/A5_KanBan/render"
    }
  },
  "status": 200
}

The traceId is always included, it links this render to any created history record or print task, making it useful for cross-referencing even in laconic mode.

The envelope around data is the one every endpoint uses: a render reports a single page in meta.pagination and carries no page links. See Response Structure on Meet the API.

Mailing the Rendering

A render request can carry an optional mailing segment. Once the render succeeded, VeloxFactory sends an HTML mail through a configured mailer, using a configured mail template, with the PDF attached and, on request, an xlsx export of the same data.

POST /api/v1/report-config/DeliveryNote/render

{
  "outputType": "base64",
  "parameters": { "P_ORDER_NO": "4711" },
  "createHistoryRecord": true,
  "createPrintTask": false,
  "mailing": {
    "mailer": "Office SMTP",
    "mailTemplate": "Report Delivery",
    "to": ["[data.first.customerEmail]"],
    "contactName": "[data.first.customerName]",
    "includePdf": true,
    "pdfFileName": "Order_[parameters.P_ORDER_NO]",
    "includeExcel": true,
    "includeParameters": true,
    "sendAsync": false
  }
}

mailer and mailTemplate take the ID or the unique name of the master data record. Recipients, contact name and attachment names accept the same placeholders as the mail template, which is what makes the segment useful for reports fed by an SQL adapter: [data.first.<column>] addresses the rows the query actually fetched, so the recipient is a result of the render rather than an input to it.

The created mail task is returned in reportMailTask, next to reportPrintTask.

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.

Each poll returns one page of the waiting tasks, oldest first: 25 by default, up to 100 with perPage. A poller that reports every task back via set-status can simply request the first page again, finished tasks drop out of the pending filter by themselves. meta.pagination.total tells how many tasks are still waiting, see Pagination.

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.

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.

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

VeloxFactory does not talk to printers directly. A companion Windows application, the VeloxFactory Print Service, runs on any machine that has the target printers installed. It receives print tasks from VeloxFactory, prints the PDF on the right printer and reports the result back. Both sides communicate only over the VeloxFactory REST API and the WebSocket server (Laravel Reverb). There is no shared database and no shared file system.

This chapter describes version 2.0.

At a glance

How it works

VeloxFactory                               Print Service (Windows)
------------                               -----------------------
Print task created  -- WebSocket event -->  Receiver (WebSocket / poll)
                    <-- GET task + PDF ---  Journal: known task? skip
                                            Worker -> printer lock -> PDFium -> Windows spooler
                    <-- set-printed -------  Outbox (retried until delivered)
                    <-- set-status error --  on permanent failures

1. Receive. A new print task triggers the WebSocket event report-print-task.created on the private channel private-report-print-tasks. The event only carries the task id and the broadcast id. In addition, the service polls the pending tasks of its broadcast ids (details in Receiving and processing print tasks).
2. Fetch. The service loads the task including the PDF (withMedia=true). The printer machine therefore needs HTTP access to VeloxFactory, not only WebSocket access.
3. Deduplicate. The job journal decides whether the task is new. Known tasks are skipped.
4. Print. A worker takes the task, waits for the printer if another job is running on it, checks the Windows queue (offline, paper out) and prints. Transient problems are retried.
5. Confirm. Success is written to the outbox first and then sent with PATCH /api/v1/report-print-task/{id}/set-printed. If VeloxFactory is unreachable, the outbox retries until it succeeds. Permanent failures are reported with set-status and a categorised error message.

Operating modes

A named mutex per instance makes sure only one engine runs. The window detects a running headless engine automatically and switches to monitor mode.

In this chapter

The Print Service has no installer. The program is delivered as a git repository that contains only the released build. Updates are a git checkout, driven by a script that stops the service gracefully first. Configuration, token, job journal and logs live in a separate data folder and survive every update.

Requirements

Folder layout

C:\kiwisoftware\VeloxPrint\
  app\          clone of the release repository, program only, updated by update.ps1
    bin\        kiwisoftware.VeloxFactory.PrintService.App.exe and its libraries
    update.ps1
    README.md
  data\         created by the app, never part of git
    config.json     configuration without token
    secrets.json    API token, encrypted
    state.db        job journal, outbox, statistics, log buffer, engine status (SQLite)
    logs\           rolling log files

Where the data folder is:

1. --config <path> sets it explicitly: all files of the instance live next to that configuration file.
2. If the program runs from a folder named app or below it, the data folder is data next to that app folder.
3. Otherwise it is %ProgramData%\kiwisoftware\VeloxPrint\.

The first start with administrator rights creates the data folder and sets these permissions. Setting up the scheduled task adds the service account.

First installation

1. Create the service account

The scheduled task runs under its own account. It must exist before the task is set up, the Print Service does not create it. PowerShell as administrator:

$pw = Read-Host -AsSecureString "Password"
New-LocalUser -Name "svc-veloxprint" -Password $pw -FullName "VeloxFactory Print Service" `
  -Description "Service account VeloxFactory Print Service" -PasswordNeverExpires -UserMayNotChangePassword

1. Do not add the account to the Administrators group, the standard Users group is enough.
2. Use -PasswordNeverExpires. An expired password stops the task until it is set up again.
3. For printers on a print server in a domain, use a domain account (DOMAIN\svc-veloxprint) instead. Only a domain account can authenticate at the print server.
4. Do not use SYSTEM. It accesses print servers with the computer account, shares often refuse that.

2. Clone the release

PowerShell as administrator:

New-Item -ItemType Directory C:\kiwisoftware\VeloxPrint
git clone https://git.fischernetz.xyz/bfischer/veloxfactory-printservice-release.git C:\kiwisoftware\VeloxPrint\app

3. Configure

1. Start C:\kiwisoftware\VeloxPrint\app\bin\kiwisoftware.VeloxFactory.PrintService.App.exe as administrator. The first elevated start creates data\ and restricts its permissions.
2. Settings → Connection: base URL of VeloxFactory and API token. Test connection checks reachability, token, channel authorization, WebSocket handshake and rate limit headers.
3. Settings → WebSocket (Reverb): host, port, scheme and app key of your Reverb server.
4. Settings → Receiving: the broadcast ids of this site.
5. Save. See the Configuration reference for every setting.

4. Set up the scheduled task

Settings → Operation → Set up scheduled task, enter the service account (.\svc-veloxprint for a local account) and its password. Alternatively on the command line (as administrator):

& "C:\kiwisoftware\VeloxPrint\app\bin\kiwisoftware.VeloxFactory.PrintService.App.exe" --install-task --user .\svc-veloxprint

The setup:

1. grants the account the right Log on as a batch job,
2. sets the permissions of the data folder and secrets.json for the account,
3. registers the Windows event log source VeloxFactory Print Service,
4. creates or updates the task with the settings below.

The window shows the task under Settings → Operation: state, account, last and next run, last result and the XML definition. It can start and remove the task there, too.

5. Verify

1. Printers: print a test page on every printer the site uses.
2. Start the task (Settings → Operation → Start or reboot). The window switches to monitor mode.
3. Create a print task in VeloxFactory for one of the broadcast ids and watch it on the Dashboard.

Updates and rollback

PowerShell as administrator:

# newest release
powershell -ExecutionPolicy Bypass -File C:\kiwisoftware\VeloxPrint\app\update.ps1

# a specific release, also the way back to an older one
powershell -ExecutionPolicy Bypass -File C:\kiwisoftware\VeloxPrint\app\update.ps1 -Version 2.0.1

1. Releases are git tags (v2.0.1). git -C C:\kiwisoftware\VeloxPrint\app log --oneline shows the source commit of every release.
2. New settings are added to config.json with their defaults on the next start.
3. Never change files inside app\. The script refuses to update a modified folder. Settings belong into data\.

Several instances on one machine

Each instance needs its own configuration file. Its name becomes the prefix of all files of the instance, so several instances can share one data folder:

data\config.json               default instance
data\lager-nord.json           second instance
data\lager-nord.secrets.json
data\lager-nord.state.db
data\logs\lager-nord\

$exe = "C:\kiwisoftware\VeloxPrint\app\bin\kiwisoftware.VeloxFactory.PrintService.App.exe"
& $exe --config C:\kiwisoftware\VeloxPrint\data\lager-nord.json                                   # window of this instance
& $exe --config C:\kiwisoftware\VeloxPrint\data\lager-nord.json --install-task --user .\svc-veloxprint

The task of that instance is called VeloxFactory Print Service (lager-nord). Give every instance its own broadcast ids.

All settings of an instance live in config.json in the data folder (see Installation and updates). The API token is not part of it, it is stored encrypted in secrets.json. Normally you edit everything in the window under Settings. The file can also be edited in a text editor, the running engine picks up the change by itself.

How the configuration is handled

Example

{
  "schemaVersion": 1,
  "instance": { "id": "5d0c2f4e-...", "name": "Warehouse North", "serviceAccount": "SRV01\\svc-veloxprint" },
  "api": { "baseUrl": "https://vf.example.com", "timeoutSeconds": 30, "allowUnencrypted": false, "serverTimeZone": "Europe/Berlin" },
  "receive": {
    "mode": "Hybrid",
    "broadcastIds": ["Standard", "Warehouse"],
    "includeWithoutBroadcastId": false,
    "pollingIntervalSeconds": 30,
    "safetyPollIntervalSeconds": 120,
    "pageSize": 10
  },
  "websocket": { "scheme": "wss", "host": "vf.example.com", "port": 443, "appKey": "your-reverb-app-key", "channel": "private-report-print-tasks" },
  "processing": {
    "paused": false, "pauseReason": null, "pausedUntil": null,
    "maxParallelJobs": 4,
    "serializePerPrinter": true,
    "retryCount": 3,
    "retryBackoffSeconds": [5, 30, 120],
    "printTimeoutSeconds": 120,
    "confirmation": "Spooled",
    "dryRunFolder": null
  },
  "printerDefaults": { "scaling": "ActualSize", "autoRotate": true, "dpi": null, "copiesMode": "Driver", "paperSource": null, "duplex": "Default", "color": "Default" },
  "printers": [
    { "queueName": "WH-LABEL-01", "localName": "\\\\printsrv01\\WH-LABEL-01", "dpi": 300 },
    { "queueName": "PDF24", "copiesMode": "Loop" }
  ],
  "logging": { "minimumLevel": "Information", "retentionDays": 30, "maxFileSizeMb": 250, "eventLog": true, "jsonFile": false },
  "statistics": { "retentionDays": 365, "resetAt": null },
  "health": { "enabled": false, "port": 8765 },
  "ui": { "errorNotifications": true, "windowWidth": null, "windowHeight": null, "windowMaximized": false }
}

instance

api

The API token is entered in Settings → Connection and stored in secrets.json. Required rights: global:use-api, report-print-task:read, report-print-task:update, optional printer:read. The token never appears in logs, exports or diagnostic packages.

receive

websocket

Ignored in mode Polling. The URL is built as {scheme}://{host}:{port}/app/{appKey}?protocol=7&client=veloxprint&version={x}.

processing

printerDefaults and printers

printerDefaults applies to every printer. An entry in printers overrides single values for one queue name; a value missing there (or null) falls back to the default. Details and advice in Printers and printing.

logging, statistics, health, ui

This page follows a print task through the Print Service: how it arrives, which instance takes it, how it is printed, retried and confirmed, and what protects it against being printed twice.

Receive modes

Why the safety poll

Reverb delivers an event once and does not keep it. An event sent during a short network interruption is lost, and a connection can look alive without delivering events. The safety poll finds such tasks at the latest after its interval. Tasks the journal already knows are skipped, so polling never prints twice.

The poll request

GET /api/v1/report-print-task?status=pending&perPage=10&page=1&withMedia=true
    &withRelations=false&withAudit=true&broadcastId=Standard,Warehouse&withoutBroadcastId=false

1. The filter runs on the server: only tasks of the own broadcast ids are returned.
2. withMedia=true delivers the PDFs directly, no second request per task.
3. withAudit=true delivers the creation time for the lead time statistics.
4. If more pages exist, the next page is requested immediately instead of after the interval.

The WebSocket connection

1. Pusher protocol 7 against Laravel Reverb, private channel private-report-print-tasks, authorized with POST /api/v1/broadcasting/auth and the API token.
2. The event report-print-task.created carries { model, id, broadcastId }. If the broadcast id matches, the service loads the task with GET /api/v1/report-print-task/{id}?withMedia=true.
3. Keep-alive: every pusher:ping of the server is answered with pusher:pong. After 25 s without traffic the service sends its own ping and drops the connection if no pong arrives within 30 s.
4. Reconnect with exponential backoff from 1 s to 60 s, ±20 % jitter. After every successful subscribe a catch-up poll fetches what was created in the meantime.
5. A first connection failure is logged as warning. An outage longer than 5 minutes writes event id 3000.

Broadcast ids: which instance prints what

Every print task and every printer in VeloxFactory can carry a broadcast id, usually one per site or printer group. An instance only takes tasks whose broadcast id is in its receive.broadcastIds, both from events and from polls.

Tasks without broadcast id are taken only with includeWithoutBroadcastId. VeloxFactory sends no WebSocket event for them, so they arrive only by polling: in Hybrid within safetyPollIntervalSeconds, in mode WebSocket only at start and after a reconnect. Give print tasks a broadcast id whenever they should print immediately.

Rate limit

The VeloxFactory API limits requests per IP address, by default 10 per minute (API_RATE_LIMIT_PER_MINUTE). The service reads the limit from X-RateLimit-Limit and the rest from X-RateLimit-Remaining in every response and shows both on the dashboard.

1. On HTTP 429 every API call of the process waits until Retry-After (60 s if the header is missing), then the same request is sent again. Print tasks wait, they do not fail. The API state shows Rate limited, event id 2002 is written.
2. The service does not slow down in advance. A low remaining count is only displayed.
3. Settings → Receiving shows the base load of the chosen mode in calls per minute (Hybrid with 120 s: 0.5) and warns when it exceeds half of the limit.
4. The limit counts per IP. All print services, scripts and MCP clients behind the same NAT share it. For print environments raise API_RATE_LIMIT_PER_MINUTE in the .env of your VeloxFactory instance.

Processing

Receiver -> queue -> journal check -> worker (max. maxParallelJobs) -> printer lock -> queue check -> print -> outbox

1. Journal check. A task the journal knows in state Printing or later is skipped. A task that was confirmed or reported before and is pending again (reprint) is loaded fresh; only if VeloxFactory really shows it as pending is it printed again.
2. Fetch. Tasks from a WebSocket event are loaded now, tasks from a poll already carry their PDF. A task that no longer exists or is no longer pending is dropped.
3. Printer. The queue name of the task is resolved to the local printer (alias, see Printers and printing). The Windows default printer is never used; a task without printer name fails with PrinterNotFound.
4. Printer lock. With serializePerPrinter only one job runs per printer, ordered by task id. Jobs for different printers run in parallel up to maxParallelJobs.
5. Queue check. Before printing, the Windows queue is checked. Not installed fails immediately. Offline, paper problem or error goes into retry without printing.
6. Print. See Printers and printing. The spooler document name is VF #{id} {file name}, so the job can be found in the Windows print queue.
7. Confirm. With confirmation = Spooled the task is confirmed as soon as the spooler accepted it. With Completed the service waits until the spooler job has finished (at most printTimeoutSeconds).

Retries

With the defaults (retryCount 3, retryBackoffSeconds [5, 30, 120]) a task waits about 2.5 minutes before it is reported as failed. For label printers that are offline longer, for example during a roll change, use more retries or a longer last value, e.g. [5, 30, 120, 300, 600] with retryCount 5.

Error reports

Permanent failures are reported with PATCH /api/v1/report-print-task/{id}/set-status, status error and an errorMessage of the form [Category] message, shortened to 1,000 characters. Categories: PrinterNotFound, PrinterOffline, RenderFailed, Timeout, SpoolerError, Unknown. The task shows the message in VeloxFactory.

Job journal and outbox

VeloxFactory has no endpoint to claim a task. The local journal in state.db takes that role and records every task with its state:

Outbox. Confirmations and error reports are written to the outbox first and then sent. If the API is unreachable, the outbox retries with backoff (5 s, doubling, at most every 5 minutes) until it succeeds. If VeloxFactory answers 404 (task deleted) or 422 (rejected), the entry is dropped. After a crash, spooled tasks without outbox entry get their confirmation again. The dashboard tile Queue shows open outbox entries as to confirm.

Reprint. To print a task again, use Jobs → Print again in the window. It resets the task to pending in VeloxFactory (PATCH set-printed with false), the next poll prints it. Resetting the task in VeloxFactory itself has the same effect.

Pause processing

A pause stops printing without stopping the service. Use it for printer maintenance, a roll change or while wrong tasks are cleaned up in VeloxFactory.

1. Set it on the dashboard (Pause / Resume) or under Settings → Processing with reason and optional end time. The pause is stored in config.json, so it survives a restart and a pause set in the window also pauses the headless engine.
2. While paused: the WebSocket stays connected, events are noted but not processed, periodic polls are skipped. Tasks already in the pipeline wait before their next print attempt; the waiting time does not count as a retry. A print call already in progress is not interrupted. The outbox keeps delivering confirmations.
3. New tasks stay pending in VeloxFactory.
4. On resume the service polls immediately and prints everything that arrived meanwhile.
5. The engine state is Paused with reason and end time. The health endpoint still answers 200.

Dry run

For tests and demonstrations without paper. With processing.dryRunFolder set (or --dry-run <folder> on the command line, which applies to that run only) every task is received, fetched and resolved as usual, but instead of printing the PDF is written to <folder>\<task id>_<file name>. Nothing is confirmed, the task stays pending in VeloxFactory.

A print task names its printer by the printerName of the VeloxFactory printer master data (see Printers: master data for your print targets). The Print Service calls this the queue name and maps it to a Windows printer on its machine. This page covers that mapping, the per-printer settings, how pages are printed and which printers are not suitable.

Installing printers for the service

The headless service runs under its own account without a desktop. What that account cannot see, it cannot print on.

Install a print server connection machine-wide (as administrator, takes effect after the spooler restarts or the next logon):

rundll32 printui.dll,PrintUIEntry /ga /n\\printsrv01\WH-LABEL-01
Restart-Service Spooler

The printer list

The Printers page of the window compares four sources:

1. the VeloxFactory printer master data (GET /api/v1/printer, needs printer:read), filtered on the own broadcast ids. Printers without broadcast id only appear with includeWithoutBroadcastId,
2. the printers installed on this machine,
3. printers with own settings in config.json,
4. printers that received jobs in the last 7 days but are in none of the sources above (Only in recent print jobs).

Local printers that no row points to are listed at the end as Not in VeloxFactory, useful as alias targets and for test pages.

Actions per row: copy the printer name, print a test page, edit the printer settings, open the Windows print queue.

Alias: local printer name

The alias (localName) sends the jobs of a queue name to a Windows printer with a different name. VeloxFactory does not need to know about it.

"printers": [
  { "queueName": "WH-LABEL-01", "localName": "\\\\printsrv01\\WH-LABEL-01" },
  { "queueName": "OFFICE-A4",   "localName": "Brother HL-L3210CW series Printer" }
]

1. Without alias the Windows printer must have exactly the queue name (case-insensitive).
2. Typical uses: the same printer has a different name on every workstation, a temporary replacement printer, or a PDF printer for tests.
3. The alias is set in the printer editor, field Local name. The same name as the queue name, or empty, stores no alias.
4. The alias lives in the local config.json. Every machine needs its own entry.

Printer settings

printerDefaults in Settings → Printer defaults applies to all printers. The printer editor on the Printers page overrides single values for one printer (Use default keeps the default). The effective value is: printer override, else default, else the driver's setting.

All settings apply to the single print job only. The service never changes the configuration of the Windows printer. Some drivers ignore job settings for duplex, colour or tray and use their own defaults; in that case change the setting in the printing preferences of the Windows printer.

How pages are printed

1. The PDF stays in memory, nothing is written to disk.
2. PDFium (the PDF engine of Chromium) draws every page directly onto the device context of the printer, in the device resolution and without an intermediate bitmap. Text, lines and barcodes are sent as vector graphics and print as sharp as the printer can.
3. The target rectangle is computed per page from the printer's resolution and printable area, so pages of different size or orientation in one document work.
4. Output uses the Windows spooler without any print dialog. The document name in the spooler is VF #{task id} {file name}.
5. PDFium is not thread-safe; its calls are serialised inside the service, jobs on different printers still run in parallel.

Limitations:

1. Pages with transparency (for example PNG images with alpha channel) are output by PDFium as an image in device resolution.
2. Form fields (AcroForm) are not printed.
3. Lines with width 0 in the PDF are drawn as the thinnest line the device can print, one printer dot. On high-resolution printers they become very thin. Give lines and borders in the JRXML an explicit width, e.g. lineWidth="0.5".

Printers that open a dialog

Some printers ask for a file name or open an application window when printing. In the headless service there is no desktop: the dialog is invisible and waits forever. The job ends after printTimeoutSeconds and is reported as Timeout.

The service marks these printers with Prints with a dialog, not suitable headless. Detected by port (PORTPROMPT:, XPSPort:, PDF24:, FAX:, SHRFAX:) or driver name (Microsoft Print To PDF, Microsoft XPS Document Writer, OneNote, PDF24, Fax). In the window they work, the test page asks for confirmation first. For PDF tests without dialog use the dry run or configure PDF24 with automatic saving.

Test page

The test page is an A4 PDF in the VeloxFactory design, generated locally without API access. It contains instance name, printer, time and account, a line pair pattern that shows the effective resolution, grey scale steps, a Code 39 barcode and a frame 10 mm from the paper edge to check margins and scaling. It is printed with the settings of the printer, including alias.

Print it from the Printers page or on the command line:

& "C:\kiwisoftware\VeloxPrint\app\bin\kiwisoftware.VeloxFactory.PrintService.App.exe" --test-print WH-LABEL-01

Started without parameters, the Print Service opens its window in the VeloxFactory design (light, dark or system theme). The header shows the pages, the instance name and the mode badge: Interactive when the engine runs inside the window, Monitor when a headless engine runs and the window only shows its state. Screenshots follow.

Dashboard

Below the tiles: the last 20 jobs and the last 5 errors. A click opens the job.

Console

The live log, written for users: Task #4711 received (WebSocket, Standard) → WH-LABEL-01, 2 copies instead of raw protocol events.

1. Columns: time, level (icon and colour), area (API, WS, Print, Engine), task, message.
2. Filters: levels as chips, area, text search, a single task, errors only. Clear filters resets them.
3. Autoscroll can be paused. Copy a line, export the selection or all visible lines, click a task to open it.
4. Protocol details (ping, pong, channel auth) are logged on level Debug and hidden by default.
5. Buffer: 10,000 lines in the window. In monitor mode the lines come from state.db, which keeps the last 50,000 entries.

Jobs

The local history from the job journal: id, time, printer, file, copies, pages, channel (WebSocket or poll), duration, status, trace id. Filters for period, status and printer, search by #id, file name, trace id or error text.

The detail view shows the timeline of states, error text and attempts. Actions:

Printers

Comparison of VeloxFactory printers, local printers, own settings and printers of recent jobs, with state, hints, test page, printer editor and a link to the Windows print queue. Described in Printers and printing.

Statistics

Local statistics of this instance, nothing is sent to VeloxFactory.

1. Tiles for today and 7 days: jobs printed and failed, error rate, pages.
2. Jobs over time per hour (24 h, 7 days, 30 days), pages and copies per printer, top error categories.
3. Lead time from creation in VeloxFactory to confirmation (median, P95), share of WebSocket and poll, WebSocket availability and reconnects, API calls and 429 events.
4. Export as CSV. The mouse wheel over a chart zooms the chart only.
5. Retention statistics.retentionDays (365 days); after 30 days the data is kept as daily aggregates.

Settings

1. Save writes config.json, the engine applies it without restart. Unsaved changes are asked for when leaving the page.
2. Test connection checks: reachability, token (GET /report-print-task?perPage=1), printer master data (printer:read), channel authorization and WebSocket handshake (15 s), rate limit headers compared with the base load.
3. Reset statistics counts from now on. The job journal stays, it protects against double printing.
4. Clear logs empties the console history and deletes all log files of the instance except today's.
5. Without write access to the data folder the window offers Restart as administrator.

Info

Version, .NET runtime, Windows account (with Administrator when elevated), mode, instance id, paths of configuration, data and log folder with buttons to open them, and Create support package (see Monitoring and troubleshooting).

Notification area

In interactive and monitor mode the Print Service has a tray icon with status colour (green OK, yellow warning, red error) and a menu: open, pause, exit. Closing the window hides it in the notification area; in interactive mode the engine keeps running. Exit stops the engine gracefully: running jobs finish, the outbox is flushed. Print errors show a Windows notification unless ui.errorNotifications is off.

The program file is kiwisoftware.VeloxFactory.PrintService.App.exe in app\bin. Without parameters it opens the window. All other functions are available as parameters, for the scheduled task, scripts and software distribution.

Parameters

1. Paths (--config, --dry-run, --support-package) must be absolute. The Task Scheduler starts in C:\Windows\System32, a relative path would end up there.
2. Mapped network drives do not exist for the service account. Use local paths or UNC paths.
3. An unknown parameter or a missing value prints the usage and ends with exit code 1.

Exit codes

Exit codes 1 and 3 of a headless start are visible in the Task Scheduler as Last run result. The Task Scheduler restarts the task every minute; fix the configuration or token, the next start picks it up.

Examples

$exe = "C:\kiwisoftware\VeloxPrint\app\bin\kiwisoftware.VeloxFactory.PrintService.App.exe"

# check configuration and connection
& $exe --validate-config
#   Configuration: C:\kiwisoftware\VeloxPrint\data\config.json
#   [OK]      Configuration is valid
#   [OK      ] Reachability: https://vf.example.com
#   [OK      ] Token: Token accepted, report-print-task:read granted.
#   [OK      ] WebSocket: Subscribed to private-report-print-tasks on vf.example.com:443.

# scheduled task for the default instance and for a second instance
& $exe --install-task --user .\svc-veloxprint
& $exe --config C:\kiwisoftware\VeloxPrint\data\lager-nord.json --install-task --user .\svc-veloxprint

# test page
& $exe --test-print WH-LABEL-01

# engine in a console window for debugging (stop the scheduled task first)
& $exe --headless --console

# dry run into a folder
& $exe --dry-run C:\Temp\veloxprint-dryrun --console

# diagnostic package
& $exe --support-package C:\Temp\veloxprint-support.zip

# graceful stop of the default instance
& $exe --stop

The headless service has no window, so it reports through log files, the Windows event log and an optional local health endpoint. For support cases it bundles everything into one diagnostic package.

Log files

data\logs\veloxprint-20260925.log
data\logs\veloxprint-20260925_001.log        same day, after the size limit
data\logs\veloxprint-20260925.json           optional, logging.jsonFile
data\logs\lager-nord\veloxprint-...          instance with --config lager-nord.json

2026-09-25 07:16:48.120 +02:00 [INF] [Print] [#35] Task #35 received (WebSocket, Standard) -> WH-LABEL-01, 1 copy
2026-09-25 07:16:49.402 +02:00 [INF] [Print] [#35] Task #35 spooled to WH-LABEL-01, 1 page
2026-09-25 07:16:49.655 +02:00 [INF] [API] Task #35 confirmed as printed

Format: time with offset, level (VRB, DBG, INF, WRN, ERR, FTL), area (API, WS, Print, Engine), task id where known, message.

1. One file per day, a new file (_001, _002) when logging.maxFileSizeMb (250 MB) is reached.
2. Files older than logging.retentionDays (30) are deleted, by age, not by count.
3. Lines of a task carry its task id and trace id; the trace id links it to the history record and print task in VeloxFactory.
4. The API token never appears in any log.

Windows event log

Warnings and errors go to the event log Application, source VeloxFactory Print Service, with fixed event ids for monitoring systems such as Checkmk, PRTG, Zabbix or SCOM. The source is registered when the scheduled task is set up; without it the event log output stays off. Switch it off with logging.eventLog.

Local health endpoint

Optional, switched on under Settings → Operation (health.enabled, port health.port, default 8765). It listens only on 127.0.0.1, needs no URL reservation and no administrator rights, and is not reachable from other machines. A monitoring agent on the same machine polls it.

GET http://localhost:8765/health

{
  "status": "ok",
  "engine": "Running",
  "hostMode": "Headless",
  "version": "2.0.1",
  "startedAt": "2026-09-25T05:01:12+00:00",
  "api": {
    "state": "Ok",
    "lastApiSuccess": "2026-09-25T07:16:49+00:00",
    "lastApiError": null,
    "rateLimit": { "limit": 60, "remaining": 58, "rateLimitedUntil": null }
  },
  "websocket": { "state": "Subscribed", "since": "2026-09-25T05:01:14+00:00", "reconnectAttempt": 0 },
  "queue": { "active": 0, "waiting": 0, "retrying": 0, "outbox": 0 },
  "printers": { "ok": 3, "withProblems": 0 }
}

Worth alerting on besides the status: queue.outbox above 0 for a longer time (printed but not confirmed), queue.retrying above 0 (printer problem), printers.withProblems above 0, websocket.state not Subscribed.

Diagnostic package

Info → Create support package, or --support-package C:\Temp\support.zip. The ZIP contains:

The API token is removed from every file.

Common problems

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.