The Basics What is VeloxFactory? VeloxFactory is a web application that lets you manage and render JasperReports templates โ€” via a clean frontend, a powerful REST API, or both. It turns the well-established JasperReports engine into something any application can consume with a single HTTP call. ๐Ÿ–ฅ๏ธ Desktop only โ€” by design. VeloxFactory's views are complex enough that a proper mobile experience requires dedicated work. The application is intentionally optimised for desktop browsers โ€” a minimum resolution of 1600ร—900 is recommended; anything below that will work, but becomes cumbersome to navigate. A mobile-friendly version is on the roadmap, but not imminent. Where VeloxFactory Fits JasperReports is a mature, battle-tested report engine. It produces high-quality PDFs, supports complex layouts, barcodes, images, and dynamic data โ€” and it has been doing so reliably for decades. Integrating it directly requires a JVM on your server and Java code to drive it โ€” which is a natural fit for Java stacks, but an overhead most PHP, Python, or C# teams prefer to avoid. VeloxFactory sits on top of the JasperReports render engine and exposes its capabilities via a clean REST API and a management frontend. The render engine runs in pure PHP โ€” no JVM process required on your application server. You design your report templates in Jaspersoft Studio as usual, upload them once, and from that point on โ€” rendering is just a POST request. POST /api/v1/report-config/A5_KanBan/render Content-Type: application/json Authorization: Bearer { "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. A permission system. What started as "just get me a label PDF" is now a full suite โ€” and the name stuck, question mark and all. What VeloxFactory Does At its core, VeloxFactory does four 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. Who It Is For VeloxFactory is for anyone who needs to generate documents โ€” labels, reports, delivery notes, production sheets, certificates โ€” reliably and programmatically. The typical home is in logistics, production, and warehousing, where printing article labels, kanban cards, or shipment documents is a daily operational need and downtime is not an option. More broadly: if your application needs to produce a PDF from structured data, and you do not want to build and maintain a report engine yourself, VeloxFactory is the answer. Deployment VeloxFactory is a standard Laravel application. It runs wherever PHP runs โ€” which is nearly everywhere. Scenario Works? Cloud VM or VPS Yes On-premise server Yes Docker container Yes Raspberry Pi on the shop floor Yes Jaspersoft Server Not needed The setup is intentionally slim. PHP, a database for VeloxFactory itself, and the JasperPHP render engine โ€” that is the stack. No application server, no JVM process to manage, no separate Jaspersoft infrastructure. VeloxFactory bundles everything it needs. โ„น๏ธ Want to try it first? A live demo is available at demo.veloxfactory.kiwi-software.dev. Login: demo@velox.factory ย ยทย  Password: demo Our Vision VeloxFactory exists because good software should not be complicated, expensive, or opaque. This page explains what we are building towards and how we think about working with the people who use it. Simple by Design The goal behind VeloxFactory has always been the same: take a powerful but complex technology and make it accessible to teams who just need it to work. Not teams with a dedicated Java architect. Not teams with a six-figure infrastructure budget. Teams with a problem to solve and a deadline to meet. That philosophy shapes every decision in VeloxFactory โ€” from the API design to the frontend workflows. Concepts should be easy to grasp. Setup should be fast. Day-to-day use should feel obvious, even for someone who has never heard of JasperReports. Reliable and Performant Simple does not mean limited. VeloxFactory is designed to handle real production workloads โ€” in logistics, on the shop floor, in warehouses where a label printer needs to respond in milliseconds and cannot afford to fail during a shift. The architecture reflects this. The stack is intentionally slim โ€” no unnecessary layers, no bloat. Rendering is synchronous and fast. The application runs comfortably on modest hardware, including single-board computers deployed directly in production environments. When VeloxFactory is running, it runs. That is the expectation we build to. No Lock-In VeloxFactory is built exclusively on open-source components. There is no proprietary cloud dependency, no mandatory subscription, no remote kill switch. You run it where you want โ€” on your own server, in your own cloud account, on a machine on your shop floor โ€” and it stays yours. The report templates you design in Jaspersoft Studio are standard .jrxml files. The database you connect to is your own. The PDFs it produces belong to you. VeloxFactory is infrastructure you own and control, not a service you rent. Grows With You Most customers start with a single, focused use case โ€” generating an article label, a delivery note, a production sheet. VeloxFactory handles that out of the box. But as requirements evolve, the platform grows with them. History records for traceability. Print task dispatching via WebSocket. Multi-report management with a structured permission system. API access for any system that can make an HTTP call. None of these need to be in scope on day one โ€” but they are all there when the time comes. Beyond the built-in capabilities, VeloxFactory is extended on request. If a workflow requires something specific, it can be built in. Licenses include continued development and updates โ€” the software does not freeze at the point of purchase. A Real Partner VeloxFactory is not sold by a faceless vendor with a tiered support portal. It is built and maintained by someone with deep hands-on experience in logistics IT, system integration, and shop floor environments โ€” and that experience is available directly to every customer. This means practical help where it matters: rolling out the application, connecting it to existing ERP or WMS systems, adapting report templates to operational realities, and making sure the implementation actually works in the environment it needs to run in โ€” not just in a demo. The goal is not a one-time sale. It is a long-term working relationship with customers who have real problems and need a partner who understands them. The Full Picture To put it plainly: VeloxFactory is powerful software at a reasonable price, built on open foundations, designed to be simple to operate, and backed by someone who will pick up the phone. If that sounds like what you need โ€” welcome. Installing VeloxFactory VeloxFactory is a standard Laravel application. The setup is intentionally slim โ€” pull the repository, install dependencies, configure the environment, migrate the database. A standard installation is up and running in under 30 minutes. What You Don't Need Before listing what is required, it is worth being explicit about what is not: No Java โ€” the render engine is pure PHP. No JVM, no Java runtime, no Java SQL drivers. No Node.js / npm / Vite โ€” the frontend assets are pre-built and bundled with the repository. No Jaspersoft Server โ€” VeloxFactory is entirely self-contained. No Docker โ€” optional for the database only, not required for the application itself. System Requirements Requirement Notes PHP >= 8.2 Required extensions: ctype, curl, fileinfo, filter, hash, mbstring, openssl, pcntl, pdo, pdo_sqlite, posix, redis, session, simplexml, tokenizer. For report database connections, additionally: pdo_mysql (MySQL / MariaDB), pdo_pgsql (PostgreSQL). SQL Server is listed separately below. Composer PHP dependency manager โ€” getcomposer.org MySQL or MariaDB VeloxFactory's own application database. A Docker container works fine if no local instance is available. Redis Required for the queue driver (Laravel Horizon). Install via apt install redis-server or run as a Docker container. The php-redis extension must also be installed: apt install php-redis. See Background Job Processing for details. poppler-utils Provides pdftoppm, used for generating report thumbnails. Install via apt install poppler-utils. Supervisor Keeps the three background processes running: Horizon (queue workers), Reverb (WebSocket server), and the Scheduler. See Background Job Processing for the full Supervisor configuration. Apache2 or nginx Optional reverse proxy. Not required for local or development setups. php-sqlsrv / pdo_sqlsrv Only required when connecting to Microsoft SQL Server as a report data source. Not needed otherwise. Bundled Dependencies The following components are bundled with VeloxFactory โ€” no separate installation required: Component Purpose JasperPHP Pure PHP render engine โ€” parses .jrxml and generates PDFs via TCPDF. Installed automatically by Composer. Laravel Horizon Redis-backed queue manager with built-in dashboard. Manages worker pools for thumbnail generation and nightly purge jobs. Installed automatically by Composer. Log Viewer In-browser Laravel log viewer for monitoring application logs. Scribe Generates the interactive API documentation from source annotations. Material Design Icons Icon set used throughout the frontend. Ace Editor In-browser code editor for writing SQL queries. Logo & Color Concept Visual identity by sinister-labs. Jaspersoft Studio 6.21.5 Desktop IDE for designing .jrxml report templates. Installed separately on the designer's machine โ€” not on the server. Download here. Deployment Options VeloxFactory can be deployed in two ways: self-hosted on your own infrastructure, or fully managed and operated by kiwi software. Both options deliver identical functionality โ€” the choice depends on your team's operational preferences and existing infrastructure. Self-Hosted You run VeloxFactory on your own servers. The infrastructure footprint is intentionally small โ€” no Java runtime, no application server, no container orchestration required. A single modest Linux VPS covers all but the most demanding workloads. Component Minimum Recommended Notes VeloxFactory server (Linux) 1 vCPU, 1 GB RAM 2 vCPU, 4 GB RAM A Hetzner CX22 (2 vCPU, 4 GB RAM, 40 GB NVMe) is more than sufficient for most deployments. Any comparable entry-level VPS or on-premises Linux server works equally well. Disk 10 GB 40 GB Application and report thumbnails. Scale with report volume and history retention period. Background Printing Service (Windows) Any Windows 10/11 machine or Windows Server with the target printers installed Runs as a lightweight console process โ€” a few dozen MB of memory, negligible CPU. In most deployments, an existing Windows PC on the shop floor or in the office serves as the print host. No dedicated hardware required. โ„น๏ธ MySQL and VeloxFactory can share the same VM for small to medium deployments. A dedicated database server is only worth considering when multiple VeloxFactory instances share one database, or under very high render throughput. Managed Hosting If you prefer not to manage infrastructure yourself, VeloxFactory can be hosted and operated for you. Instances run exclusively in Germany on Hetzner hardware โ€” reliable, fast, and GDPR-compliant by location. Updates, monitoring, and backups are handled on your behalf. Managed hosting works well for most use cases. Depending on your network connection to the hosting location, render requests may see slightly higher latency compared to a locally deployed instance โ€” typically not noticeable, but worth considering for high-frequency, latency-sensitive workloads such as real-time label printing on the shop floor. For managed hosting enquiries, get in touch directly. Configuration and data models VeloxFactory is built around a small set of interconnected models. Understanding them is the key to understanding everything else โ€” from how reports are set up, to how renderings are stored, to how print jobs are dispatched. Field Naming Conventions VeloxFactory uses two naming styles consistently throughout the system. Database columns and Laravel model attributes are always snake_case โ€” for example broadcast_id, report_config_id, created_by_token_id. The API and frontend use camelCase for all request and response fields โ€” the same fields become broadcastId, reportConfigId, createdByTokenId. This split is consistent without exception: whenever you are working with the API or the frontend, use camelCase. Whenever you are looking at raw database records, migration files, or server-side model attributes, expect snake_case. Throughout this documentation, all field names and JSON examples follow the API convention โ€” camelCase. The Model Hierarchy Every piece of data in VeloxFactory fits into a clear hierarchy. At the top sits the ReportConfig โ€” the central entity. Everything else either belongs to it, describes it, or records what happened when it was used. ReportContext โ† Organisational label for grouping reports ReportConnectionConfig โ† Optional live database connection ReportConfig โ† The report template + all its metadata โ”œโ”€โ”€ ReportParameter โ† Input values passed at render time โ”œโ”€โ”€ ReportField โ† Output columns from the SQL query or data payload โ””โ”€โ”€ ReportResource โ† Graphic file asset (image, logo) โ””โ”€โ”€ (links to) CommonReportResource โ† Shared asset reused across reports ReportHistoryRecord โ† Record of a past rendering (optional) โ””โ”€โ”€ ReportPrintTask โ† A print job dispatched from a history record ReportContext A context is a visual label you assign to report configurations to group and identify them at a glance. It carries no functional logic โ€” it is purely organisational. Field Description context_name Display name of the context context_description Short description context_text_color Hex color for the label text context_badge_color Hex color for the badge background context_border_color Hex color for the badge border Every ReportConfig requires a context. A single context can be shared across any number of report configurations. ReportConnectionConfig A connection config represents a live database connection that VeloxFactory can use as a data source when rendering a report. When assigned to a ReportConfig, VeloxFactory executes the report's SQL query against this connection at render time and feeds the result rows into the report as field data. Field Description connection_name Friendly name for this connection connection_driver Database driver (see table below) connection_host IP address of the database server connection_port Port โ€” required connection_database Database / schema name connection_username Username (stored encrypted) connection_password Password (stored encrypted) connection_test_query SQL query used to verify the connection connection_tested Whether the connection has been successfully tested Supported drivers: Driver Database mysql MySQL mariadb MariaDB pgsql PostgreSQL sqlsrv Microsoft SQL Server Connection status is derived from connection_tested: Status Meaning approved Connection has been tested successfully unapproved Never tested or last test failed โš ๏ธ A report can only be rendered with a live connection if its status is approved. VeloxFactory will reject render requests for reports whose connection has not been successfully tested. Network Requirements VeloxFactory establishes the database connection directly from the server it runs on. The target database must therefore be reachable from that host โ€” ideally within the same network or at minimum via a secured private channel. โš ๏ธ Do not expose your database to the public internet. Configuring a publicly accessible database โ€” or opening firewall ports to make one reachable โ€” is a significant security risk and is strongly discouraged. If VeloxFactory and your database run in separate networks, use an encrypted VPN tunnel instead: WireGuard or OpenVPN are both well-suited for this purpose. When is a ReportConnectionConfig needed? A ReportConnectionConfig is optional per ReportConfig. Whether you need one depends on how your report gets its data: Scenario Connection needed? Report has no detail band โ€” purely static layout No Report has a detail band, data delivered via API at render time No Report has a detail band and fetches data via SQL Yes ReportConfig The ReportConfig is the core entity of VeloxFactory. It represents a single JasperReports template โ€” the .jrxml file โ€” together with all the metadata VeloxFactory maintains about it. Field Description report_name Display name of the report report_description Optional description report_file_name Internal filename of the stored .jrxml report_width Page width in mm (extracted from the .jrxml on upload) report_height Page height in mm (extracted from the .jrxml on upload) report_query SQL query โ€” defined in VeloxFactory and stored in the database report_has_detail_band Whether the template contains a detail band (extracted on upload) report_context_id FK โ†’ ReportContext report_connection_config_id FK โ†’ ReportConnectionConfig (nullable) report_preview_base64 Base64-encoded preview image report_thumbnail_base64 Base64-encoded thumbnail image โ„น๏ธ The SQL query is not defined in the .jrxml file. It is written and managed directly in VeloxFactory and stored in the database as part of the ReportConfig. The .jrxml only defines which fields the query result maps to. When a .jrxml file is uploaded, VeloxFactory automatically analyses it and creates the associated ReportParameter, ReportField, and ReportResource records. You then review and complete the auto-generated data โ€” for example setting example values or uploading resource files. ReportParameter Parameters are the inputs passed into a report at render time โ€” dates, IDs, filter values, flags, and so on. Field Description parameter_name Parameter name as defined in the .jrxml parameter_data_type Java class name (e.g. java.lang.String, java.lang.Integer) parameter_required Read from the required custom property in the .jrxml parameter_evaluation Evaluation time, extracted from the .jrxml parameter_example_value Read from the exampleValue custom property in the .jrxml Both parameter_required and parameter_example_value are sourced from custom properties embedded in the .jrxml parameter definition. They can also be set manually in VeloxFactory after upload. ReportField Fields represent the data columns that populate the report's detail band โ€” either from an SQL query result or from a data array delivered at render time. Field Description field_name Field name as defined in the .jrxml field_data_type Java class name (e.g. java.lang.String, java.math.BigDecimal) field_example_value Read from the exampleValue custom property in the .jrxml field_example_value is used when rendering a preview without a live database connection. ReportResource Resources are graphic file assets โ€” images and logos โ€” embedded in the report template. They are referenced in the .jrxml via parameters following the P_RESOURCE_ naming convention. Field Description parameter_name The P_RESOURCE_ parameter name as referenced in the .jrxml resource_file_name Filename of the directly uploaded file (nullable) common_report_resource_id FK โ†’ CommonReportResource (nullable) A ReportResource either holds its own uploaded file or it is linked to a CommonReportResource โ€” never both at the same time. When linking to a common resource, the resource's own file is deleted and the common file is used in its place. CommonReportResource A CommonReportResource is a shared graphic asset โ€” a company logo, a standard header image โ€” that multiple report configurations can reference. Instead of uploading the same file to each report individually, you upload it once and link individual ReportResource records to it. Field Description resource_name Display name resource_description Optional description resource_file_name Internal filename of the stored file โ„น๏ธ Linking is a one-way action. When a ReportResource is linked to a CommonReportResource, its own file is permanently deleted. Unlinking removes the reference but does not restore the file โ€” you will need to re-upload it. ReportHistoryRecord A ReportHistoryRecord captures the full context of a rendering โ€” what was requested, what was returned, and whether it succeeded. Creating a history record is optional and controlled by the createHistoryRecord flag in the render request. Field Description report_config_id FK โ†’ ReportConfig trace_id Unique identifier for this rendering run output_type How the PDF was returned (see below) report_api_payload The exact request payload sent to the render call report_api_response The full API response, stored for traceability report_pdf_base64 Base64-encoded PDF content report_pdf_file_name Filename on disk report_thumbnail_base64 Base64-encoded thumbnail of the first page (generated asynchronously) status Outcome of the rendering (see below) Output types ( output_type): Value Description base64 PDF returned inline as a Base64 string url PDF stored as a file, a URL is returned preview Rendered for preview; file is not persisted none No PDF output โ€” used for print-only flows Status values ( status): Value Description ok Rendering succeeded, PDF received render_fail No errors reported, but no PDF received error JasperReports returned one or more errors unknown Status cannot be determined History records are retained for a configurable number of days โ€” see Environment Configuration below. Thumbnails are generated asynchronously after rendering completes. ReportPrintTask A ReportPrintTask represents a print job dispatched to a physical printer. It is always linked to a ReportHistoryRecord โ€” you always print a specific past rendering, not a report config directly. Field Description report_config_id FK โ†’ ReportConfig report_history_record_id FK โ†’ ReportHistoryRecord trace_id Unique identifier for this print run broadcast_id WebSocket channel ID for real-time status updates (nullable) printer_name Target printer name copies Number of copies to print output_file_name Filename of the PDF sent to the printer output_base64_string Base64-encoded PDF (consumed by the print service) error_message Error detail if printing failed status Current print status (see below) Status values ( status): Value Description pending Created, waiting for the print service printed Successfully printed and confirmed error Printing failed unknown Status cannot be determined โ„น๏ธ Real-time updates via WebSocket only apply when broadcastId is provided in the render request. The C# print service subscribes to that channel, picks up the task, executes the print job, and reports status back. Without a broadcastId, the task is created silently โ€” the print service must poll for new tasks. Audit Trail Every model in VeloxFactory tracks who created and last updated a record, and which API token was used. This information is available on all records via the withAudit=true query parameter in the API. Field Description created_at Timestamp of creation created_by User ID of the creator created_by_token_id API token ID used (if created via API) updated_at Timestamp of last update updated_by User ID of the last updater updated_by_token_id API token ID used (if updated via API) The creationMethod and updateMethod fields in the API response ( "Frontend" vs. "API") are derived automatically โ€” based on whether a token was present on the request. Environment Configuration VeloxFactory's runtime behaviour is controlled via environment variables in .env or as container environment variables. Application Variable Default Description APP_SCHEME http URL scheme for generated links ( http or https) API_RATE_LIMIT_PER_MINUTE 10 Max API requests per minute per token PAGINATION_DEFAULT_COUNT 25 Default number of results per API response Queue & Redis Variable Default Description QUEUE_CONNECTION database Queue driver โ€” must be set to redis for Horizon REDIS_CLIENT phpredis Redis client library โ€” phpredis required REDIS_HOST 127.0.0.1 Redis server hostname or IP REDIS_PORT 6379 Redis server port REDIS_PASSWORD null Redis password (leave null if not set) Horizon Variable Default Description HORIZON_PATH horizon URL path for the Horizon dashboard HORIZON_PREFIX derived from APP_NAME Redis key prefix for all Horizon data HORIZON_DOMAIN โ€” Optional custom domain for the Horizon dashboard Retention & Purge Variable Default Description PURGE_HISTORY_DAYS 30 Age in days after which history records are purged. Set to -1 to disable. PURGE_PRINTTASKS_DAYS 30 Age in days after which print tasks are purged. Set to -1 to disable. PURGE_ORPHANED_FILES_DAYS 30 Age in days after which orphaned files on disk are purged. Set to -1 to disable. Meet the frontend VeloxFactory comes with a built-in web frontend that gives you full access to every feature without writing a single line of code. It is built with Laravel Livewire โ€” a reactive framework that delivers a dynamic, app-like feel while keeping everything server-rendered. No separate JavaScript build, no SPA complexity. Navigation After logging in you land directly on the Report Configs overview โ€” the central workspace. All other sections are reachable from the main navigation. Section What you manage here Report Configs Your report templates โ€” the heart of VeloxFactory Report History Records Every past rendering with status, payload, and PDF Report Print Tasks Print jobs dispatched to the print service Report Contexts Organisational labels and visual tags for reports Report Connection Configs Live database connections for SQL-driven reports Common Report Resources Shared graphic assets reused across multiple reports Users User accounts and API token management The Lookup Pattern Every section opens with a list view โ€” powered by a Livewire Lookup component. These views work the same way across all sections, so once you know one, you know them all. Full-Text Search A search bar at the top filters records instantly as you type โ€” no page reload, no submit button. Depending on the section, the search covers names, descriptions, file names, and query text. Column Filters Each list view offers contextual filter dropdowns tailored to the entity. For Report Configs, for example, you can filter by Context, Data Adapter, Creator, or date ranges for creation and last update. Active filters are indicated by a badge count on the respective dropdown so you always see at a glance which filters are in play. Pagination Results are paginated. The default page size is controlled by the PAGINATION_DEFAULT_COUNT environment variable (default: 25). See Configuration and Data Models for all available environment settings. Working with Report Configs The Report Config section has the richest set of actions and is where most of your day-to-day work happens. Uploading a Template Report templates are designed in Jaspersoft Studio (compatible version: 6.21.5) and exported as .jrxml files. Once you have a .jrxml ready, you upload it to VeloxFactory to create a new Report Config. VeloxFactory immediately analyses the file and automatically creates all associated Parameters, Fields, and Resources โ€” based on what is defined in the template. You do not need to add these manually. After upload you review the auto-generated records: set example values where missing, assign a Data Adapter if the report uses SQL, and upload any resource files that were detected. Managing Parameters, Fields, and Resources Parameters, Fields, and Resources each have their own section within the Report Config edit view. You can edit example values, mark parameters as required, upload resource files, or link a resource to a Common Report Resource โ€” all from the same screen. Generating Previews Once all example values are set and all resource files are uploaded, you can generate a preview rendering directly from the edit view. VeloxFactory renders the report using the stored example values and stores the result as a preview image and thumbnail on the Report Config. Rendering from the Frontend You can trigger a full render directly from the frontend โ€” without touching the API. A render dialog lets you fill in parameter values, choose an output type, and optionally dispatch a print job in the same step. The result is shown inline and logged as a History Record if desired. Report Connection Configs When creating or editing a Connection Config, the form includes a Test Connection button. Use it before saving โ€” a connection must be in status approved before VeloxFactory will use it for rendering. An untested or failed connection will cause render requests to be rejected. Report History Records The History Records section gives you a full log of every rendering that was saved. For each record you can see the status, the exact parameters and data that were submitted, the raw JasperReports response, and โ€” if the rendering succeeded โ€” the resulting PDF. From a History Record you can: Download the PDF directly to your browser Trigger a print job โ€” creates a new Print Task for this specific rendering and dispatches it to the print service Report Print Tasks The Print Tasks section shows all dispatched print jobs and their current status. For each task you can inspect the target printer, number of copies, and any error messages if printing failed. If a task ended up in error state, you can reset it โ€” the task returns to pending and the print service will pick it up again. Users and API Tokens User accounts are managed under the Users section โ€” accessible to administrators only. Each user can hold one or more named API tokens, which grant API access under that user's identity. From the user edit view you can: Create a new token and copy it immediately after generation (it is only shown once) Revoke any existing token with immediate effect โš ๏ธ Copy your token immediately after creation. VeloxFactory only displays the token value once. If you lose it, you will need to revoke the old token and create a new one. Permissions Every user in VeloxFactory has a set of permissions that controls what they can see and do โ€” both in the frontend and via the API. Since both use the same underlying controllers, a permission that restricts an action in the frontend restricts the exact same action via API, and vice versa. There is no way to grant API-only or frontend-only access to a resource. Permissions fall into two categories: global and per-resource. Global permissions: Permission Effect global:admin Full access to everything, including user management global:use-api Allows use of the API and management of own API tokens Per-resource permissions โ€” available for each of the following resources: report-config, report-connection-config, report-context, report-history-record, report-print-task, common-report-resource: Permission Effect :full Full read/create/update/delete access to this resource :read View records only :create Create new records :update Edit existing records :delete Delete records global:admin always implies full access to all resources and overrides any per-resource setting. โ„น๏ธ API token permissions are inherited from the user. A token does not have its own permission set โ€” it acts with exactly the permissions of the user it belongs to. Revoking a token removes API access; the user's frontend permissions remain unaffected. Frontend vs. API โ€” What is the Difference? The short answer: there is no feature difference. The frontend calls the exact same controller methods as the API. Everything you can do in the UI, you can also automate via API. The frontend is optimised for interactive, human-driven workflows โ€” exploring reports, reviewing history records, testing connections. The API is the right choice when you want to integrate rendering into external systems, automate repetitive tasks, or process results programmatically. โ„น๏ธ Ready to explore the API? See Meet the API for authentication, query parameters, and a practical render example. Meet the API VeloxFactory ships with a fully capable REST API โ€” and it is not an afterthought. Every action you can perform in the frontend can also be performed via the API, because the frontend and the API share the same controller methods. There is no separate implementation, no feature gap, no second-class citizen. This makes the API a genuine alternative to the UI, not just an integration bolt-on. Automate report rendering in your CI pipeline, trigger prints from your ERP, manage report configurations programmatically โ€” all with the same logic that powers the frontend you already know. โ„น๏ธ For the full endpoint reference including all parameters and response schemas, explore the live demo API documentation at demo.veloxfactory.kiwi-software.dev. Login: demo@velox.factory ย ยทย  Password: demo Authentication The API uses token-based authentication via Laravel Sanctum. Every request must include a Bearer token in the Authorization header. Authorization: Bearer your-api-token Tokens are created and managed per user โ€” either from the user management section in the frontend, or via the API itself ( POST /api/v1/user/{id}/create-token). Each token can be revoked at any time. A revoked token is rejected immediately โ€” there is no grace period. { "success": false, "errors": ["This API token has been revoked."], "status": 401 } The audit trail records which token was used for every create and update operation across all models, so every API action is fully traceable. Base URL All API v1 endpoints are prefixed with: /api/v1/ Response Structure All API responses follow a consistent envelope format. Success: { "success": true, "count": 1, "data": { ... }, "meta": [], "status": 200 } Error: { "success": false, "errors": ["Descriptive error message"], "meta": {}, "status": 404 } The count field reflects the number of records in data โ€” 1 for single-record responses, the actual number of returned records for collections. The meta field carries contextual information such as the traceId of a render run. Query Parameters Most GET endpoints and the render endpoint share a common set of query parameters that control what is included in the response. They are additive โ€” combine them freely. Parameter Type Default Description limit integer 25 Maximum records to return. Set to 0 for all. withRelations boolean false Include related models (e.g. parameters, fields, resources on a ReportConfig). recursiveRelations boolean false Include nested relations within relations. withMedia boolean false Include Base64-encoded file content, previews, and thumbnails. withAudit boolean false Include the audit segment on each record (timestamps, users, token, method). Example โ€” retrieve a single report config with all relations, media, and audit data: GET /api/v1/report-config/1?withRelations=true&withMedia=true&withAudit=true Audit Segment When withAudit=true is set, every record in the response carries an audit block: "audit": { "createdAt": "2026-05-08 11:26:30", "createdByUser": 2, "createdByToken": null, "creationMethod": "Frontend", "updatedAt": "2026-05-08 13:31:35", "updatedByUser": 1, "updatedByToken": "Postman", "updateMethod": "API" } creationMethod and updateMethod are derived automatically โ€” "API" when a token was used, "Frontend" when the action came through the UI. Render-Specific Request Body The render endpoint ( POST /api/v1/report-config/{id}/render) accepts the following fields in the request body (JSON). Field Type Required Description outputType string โœ… How to return the PDF: base64, url, preview, or none createHistoryRecord boolean โœ… Whether to persist a ReportHistoryRecord for this render createPrintTask boolean โœ… Whether to create a ReportPrintTask after rendering printerName string if createPrintTask Name of the target printer useExampleValues boolean Use stored example values instead of supplying parameters manually parameters object Key-value map of parameter names to values data array Array of data rows โ€” for reports without a live DB connection numberOfCopies integer Number of print copies (default: 1) broadcastId string WebSocket channel ID โ€” triggers real-time status updates for the print task traceId string Custom trace ID; auto-generated as UUID if omitted laconicResponse boolean Strip the response to just the PDF output (see below) โš ๏ธ Output type none requires createPrintTask: true. Rendering without any output and without a print task is rejected. Laconic Responses By default, a render response is fully populated โ€” it includes the echoed input, the PDF output, the linked ReportConfig, the created ReportHistoryRecord, and the ReportPrintTask if applicable. In high-frequency or bandwidth-sensitive scenarios, add laconicResponse=true to strip everything down to just the PDF output. Rate Limiting The API enforces a configurable rate limit per token. The default is 10 requests per minute. When the limit is exceeded: { "success": false, "message": "Too many requests! The current rate limiting is 10 requests per minute.", "status": 429 } The limit is adjusted via the API_RATE_LIMIT_PER_MINUTE environment variable โ€” see Configuration and Data Models. Endpoints Overview Resource Available operations User List, show, create, update, change password, enable/disable, create/revoke tokens ReportContext List, show, create, update, delete ReportConnectionConfig List, show, create, update, delete, test connection CommonReportResource List, show, create, update, delete ReportConfig List, show, create, update, delete, update resources / parameters / fields, generate previews, render ReportResource Link / unlink CommonReportResource ReportHistoryRecord List, show, create, update, delete, print ReportPrintTask List, show, create, update, delete, set printed, set status A Practical Example: The Full Render Response A render call returns a ReportRendering object. By default it is fully populated โ€” you see the input you sent, the PDF output, and the linked records that were created. { "success": true, "count": 1, "data": { "model": "ReportRendering", "traceId": "a3f9c1d2-4e87-4b2a-9f1c-d3e8b7a20f61", "input": { "parameters": { "P_ARTICLE_NUMBER": "4561287-154" }, "data": null }, "output": { "reportPdfFileName": "a3f9c1d2-4e87-4b2a-9f1c-d3e8b7a20f61.pdf", "reportPdfBase64": "JVBERi0xLjQ...", "reportUrl": null }, "reportConfig": { "..." }, "reportHistoryRecord": { "..." }, "reportPrintTask": null }, "meta": { "traceId": "a3f9c1d2-4e87-4b2a-9f1c-d3e8b7a20f61" }, "status": 200 } Add laconicResponse=true and the response collapses to just output โ€” no echoed input, no embedded related records. Ideal for automated pipelines that only need the PDF. Try it out The demo instance gives you a fully functional VeloxFactory environment โ€” pre-loaded with report templates and example data. Everything you can do in a production setup you can do here, with one exception: print tasks do not reach a real printer. Access Demo URL: demo.veloxfactory.kiwi-software.dev Login: demo@velox.factory ย ยทย  Password: demo The demo account has full access to all report data โ€” Report Configs, History Records, Print Tasks, Connection Configs, Contexts, and Common Resources. 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 or trigger a reprint โ€” which creates a new Print 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. โ„น๏ธ Use Jaspersoft Studio 6.21.5. This is the version compatible with VeloxFactory's render engine. Download it from the Jaspersoft Community. Reports created with a significantly newer version may use features the render engine does not support. After upload, set any missing example values, upload resource files if needed, and click Generate Preview to produce a thumbnail. The report is then ready to render. Call the API Directly The demo account has API access enabled. To get a token, open the user menu in the top right corner and go to Account Settings โ†’ API Tokens โ€” copy it immediately, it is only shown once. With the token in hand, render any report with a single HTTP request: curl -X POST \ https://demo.veloxfactory.kiwi-software.dev/api/v1/report-config/{reportName}/render \ -H "Authorization: Bearer " \ -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. Explore Print Tasks When rendering via the frontend or API, enable the print task option and provide any printer name (e.g. demo-printer). VeloxFactory creates a ReportPrintTask record with status pending. Since no print service is connected to the demo, the task stays pending โ€” but you can inspect the full record and see how status tracking works. Completed print tasks are purged automatically after a configurable retention period. Demo Limitations What Behaviour in the demo Print tasks Created and traceable, but no real printer connected โ€” tasks remain pending. Completed tasks are purged automatically. Live SQL connections Connection Configs can be created and tested, but no external databases are reachable from the demo environment. User management The demo account does not have admin rights โ€” user accounts and permissions cannot be managed. Data persistence Uploaded templates, history records, and other data may be reset periodically. โ„น๏ธ Ready to go further? See Meet the Frontend for a full walkthrough of the UI, or Meet the API for complete API documentation. Open Source Attribution VeloxFactory and its companion Background Printing Service are built on open source software. We are grateful to the authors and contributors of the following packages. VeloxFactory Package License Description laravel/framework MIT The Laravel PHP framework โ€” routing, ORM, queues, and the application foundation. laravel/reverb MIT First-party Laravel WebSocket server โ€” used to broadcast print task events in real time. laravel/sanctum MIT API token authentication for the VeloxFactory REST API. laravel/tinker MIT REPL for the Laravel application. livewire/livewire MIT Full-stack component framework for the VeloxFactory frontend. opcodesio/log-viewer MIT In-browser Laravel log viewer. knuckleswtf/scribe MIT Automatic API documentation generator. quilhasoft/jasperphp MIT Pure-PHP JasperReports renderer โ€” the engine that compiles .jrxml templates and produces PDFs without a Java runtime. Background Printing Service Package License Description PdfiumViewer Apache 2.0 .NET wrapper around the PDFium library โ€” used to render and send PDFs to Windows printers. PDFium BSD 3-Clause Google's PDF rendering engine, bundled as a native binary via PdfiumViewer.Native.x86_64.v8-xfa. RestSharp Apache 2.0 HTTP client library for all API communication with VeloxFactory. Newtonsoft.Json MIT JSON serialisation and deserialisation for API responses and WebSocket messages. Serilog Apache 2.0 Structured logging to console and rolling file ( Serilog.Sinks.Console, Serilog.Sinks.File). Get VeloxFactory Interested in using VeloxFactory in your own environment? Get in touch โ€” we'll figure out the right setup together. Contact Name Benjamin Fischer E-Mail bfischer@kiwi-software.dev Website www.kiwi-software.dev What to Expect Drop a short message explaining your use case โ€” what you need to generate, how often, and whether you'd prefer self-hosted or managed. You'll hear back within one business day. If you want to explore the product first, the live demo is open: โ„น๏ธ Want to try it first? A live demo is available at demo.veloxfactory.kiwi-software.dev. Login: demo@velox.factory ย ยทย  Password: demo Smarter Code. Frischer Blick.