Skip to main content

Configuration reference

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

How the configuration is handled

Hot reload The engine watches the file and applies changes without restart. A new URL, token or WebSocket setting triggers a reconnect, running print jobs finish. Exception: of the logging settings only minimumLevel applies immediately; retention, file size, event log and JSON file take effect after a restart.
Validation On load and before saving. The window shows errors per field. A headless start with an invalid file ends with exit code 1. An invalid change while the engine runs is not applied, the engine keeps the last valid configuration and writes event id 5000.
New keys After an update the service adds keys of the new version with their defaults and writes the file (if it may). Unknown keys are reported in the log and removed on the next save.
Change log Every save is recorded with Windows account, time and changed keys in state.db. The diagnostic package contains the last 500 changes.
Export and import Settings → Import and export. The export never contains the token. The import keeps name and id of the receiving instance, check and save afterwards. Useful to roll out one configuration to several sites.
Write access Saving needs write access to the data folder. Without it the window offers Restart as administrator.

Example

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

instance

Key Default Description
id new GUID Identifies the instance (mutex, stop signal). Never copy it to another instance, an import keeps the local id.
name machine name Display name in the window, on the test page and in the diagnostic package
serviceAccount null Account of the scheduled task, written when the task is set up. Used for the file permissions.

api

Key Default Description
baseUrl empty, required Base URL of VeloxFactory without /api/v1, e.g. https://vf.example.com. All endpoints are derived from it.
timeoutSeconds 30 (5 to 300) Timeout of a single API call
allowUnencrypted false Allows http:// and ws://. Without it both are rejected, because token and PDFs would travel unencrypted. The window shows a warning banner while it is on.
serverTimeZone Europe/Berlin Time zone of the VeloxFactory instance (APP_TIMEZONE). Audit timestamps of the API carry no offset, the lead time statistics need it.

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

receive

Key Default Description
mode Hybrid Hybrid, WebSocket or Polling, see Receiving and processing print tasks
broadcastIds [] Broadcast ids this instance prints, exact match. At most 20, unique, no commas, no surrounding spaces, max. 255 characters. At least one is required unless includeWithoutBroadcastId is on.
includeWithoutBroadcastId false Also take tasks and printers without broadcast id. VeloxFactory sends no WebSocket event for such tasks, they arrive only by polling (in Hybrid after at most safetyPollIntervalSeconds). Turn it on in one instance at most.
pollingIntervalSeconds 30 (min. 1) Poll interval in mode Polling, and in Hybrid while the WebSocket is down. Below 3 s the window warns: constant API calls, the rate limit is used up quickly.
safetyPollIntervalSeconds 120 (min. 30) Safety poll in Hybrid while the WebSocket is subscribed
pageSize 10 (1 to 100) Tasks per poll page. Every page carries the PDFs, a small value keeps responses small. Further pages follow immediately.

websocket

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

Key Default Description
scheme wss wss or ws (ws only with api.allowUnencrypted)
host empty, required Host of the Reverb server as reachable from the printer machine (REVERB_HOST)
port 443 Port of the Reverb server (REVERB_PORT, behind a reverse proxy usually 443)
appKey jasper-who REVERB_APP_KEY of your VeloxFactory instance
channel private-report-print-tasks Private channel of the print task events. Must start with private-. Keep the default.

processing

Key Default Description
paused, pauseReason, pausedUntil false, null, null Maintenance pause. With pausedUntil (ISO 8601 with offset) the pause ends by itself. Survives a restart.
maxParallelJobs 4 (1 to 32) Tasks processed at the same time
serializePerPrinter true One job per printer at a time, in the order of the task ids
retryCount 3 (0 to 10) Local retries on transient errors (printer offline, paper out, spooler refused the job)
retryBackoffSeconds [5, 30, 120] Wait before retry 1, 2, 3 and so on (1 to 3600 each). With more retries than values the last value repeats.
printTimeoutSeconds 120 (10 to 3600) Limit for a print call and for the spooler wait of Completed. A driver that waits for a dialog ends here.
confirmation Spooled Spooled: confirm after handing the job to the Windows spooler. Completed: wait until the spooler job has finished. Can be overridden per printer.
dryRunFolder null Absolute local or UNC path. When set, PDFs are written there instead of printed and not confirmed. Empty = print normally.

printerDefaults and printers

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

Key Default Description
queueName only in printers, required Printer name as the print task carries it (printerName of the VeloxFactory printer). Unique, case-insensitive.
localName only in printers Alias: Windows printer that receives the jobs of this queue name. Empty = same name.
scaling ActualSize ActualSize (1:1 from the paper corner) or FitToPage (scaled into the printable area, centred)
autoRotate true Rotates a page when its orientation differs from the paper
dpi null (72 to 1200) Output resolution of the driver. Takes effect only if the driver offers exactly this resolution, otherwise the driver default stays. Empty = driver default.
copiesMode Driver Driver: one spooler job with n copies. Loop: one job per copy, for drivers that ignore the copy count (e.g. PDF24, Microsoft Print to PDF).
paperSource null Tray by name as the driver lists it. Unknown names keep the default tray.
duplex Default Default, Simplex, Vertical, Horizontal
color Default Default, Color, Monochrome (only on printers that support colour)
confirmation only in printers Overrides processing.confirmation for this printer

logging, statistics, health, ui

Key Default Description
logging.minimumLevel Information Verbose, Debug, Information, Warning, Error, Fatal. Debug shows WebSocket protocol details (ping, pong, auth). Applies immediately.
logging.retentionDays 30 (1 to 3650) Log files older than this are deleted. Takes effect after a restart.
logging.maxFileSizeMb 250 (1 to 10240) Size limit per log file; a day beyond it continues in _001, _002. Takes effect after a restart.
logging.eventLog true Warnings and errors to the Windows event log (needs the event source, created with the scheduled task). Takes effect after a restart.
logging.jsonFile false Additional log in compact JSON (veloxprint-*.json) for log collectors. Takes effect after a restart.
statistics.retentionDays 365 (30 to 3650) How long statistics are kept
statistics.resetAt null Set by Reset statistics. Jobs before this time no longer count.
health.enabled, health.port false, 8765 (1024 to 65535) Local health endpoint http://localhost:{port}/health, see Monitoring and troubleshooting
ui.errorNotifications true Windows notification of the tray icon on print errors
ui.windowWidth, windowHeight, windowMaximized null, null, false Last window size, written by the window itself

No comments to display