Printers and printing

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

Installing printers for the service

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

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