Local Printing

1Overview #

Licence. Direct Printing is a feature of Sales, bought on its own. Without it this page is not offered, the print windows list no agent printers, and every document prints through the browser's print dialog. Opening a document in its own program through the agent does not need it.

2Installing the print agent #

Once per counter computer, usually by your system administrator or software vendor.

• Get the program. On a build machine, publish it once: dotnet publish tools/CLand.PrintAgent/CLand.PrintAgent.csproj -c Release -r win-x64 --self-contained false -o publish/PrintAgent
• Check the prerequisites. Windows 10 (1809) or later with the .NET 10 Desktop Runtime and ASP.NET Core Runtime . To avoid installing runtimes, publish with --self-contained true instead; the folder is larger but needs nothing else.
• Copy the folder publish/PrintAgent to the counter, for example C:\Program Files\InvoiceNET\PrintAgent .
• Install it for the counter's Windows user. Signed in as that user, open PowerShell in the folder and run: powershell -ExecutionPolicy Bypass -File install.ps1 It adds the agent to that user's start-up programs and starts it now.
• Look for the tray icon - a small printer next to the clock (it may be under the ^ arrow). A green light means ready; amber means it is printing.

The agent runs as the signed-in user, not as a Windows service, so it can use that user's own printers, including network printers connected in their session. Install it for every Windows user who works at the counter.

3Setting up a counter #

• Install and start InvoiceNET Print Agent on this computer (it sits in the tray and starts with Windows).
• Right-click its tray icon -> Copy pairing token , paste it above and press Save Connection (F5) .
• Test Connection (F2) lists this computer's printers.
• Open a voucher, press Print , choose the format and the printer, tick Remember for … on this computer , pick Silent , and print.
• From then on, printing that voucher type - including the automatic print after saving - goes straight to that printer.

4What "Next time" means #

• Silent - no format dialog. With a printer chosen it prints straight away; with "Browser print dialog" it opens the browser's print dialog for the saved format.
• Ask - the format dialog opens with the saved format, printer and copies already chosen; F5 prints.
• Preview - no format dialog; the saved format opens in a new tab to look at. Nothing is marked printed.
• The print options button next to Print (or Ctrl+Shift+P ) always opens the format dialog, whatever is saved - for a reprint in another format.

5Rules and limits #

• Settings belong to this browser on this computer , and to the company you are in. Another computer, another browser, a private window or clearing site data starts without them.
• One setting per voucher type. Saving again from the print dialog replaces it.
• The print rights are unchanged: Print / Re-print on the voucher type and the voucher status still decide whether a voucher may print at all.
• If the agent is not running, or the printer is gone, the document opens in the browser's print dialog instead and the page says why - nothing is lost.
• The agent only listens on this computer (127.0.0.1) and only obeys a browser holding its pairing token. A new token (tray icon) disconnects every paired browser.
• Copies: 1 to 99, for a printer of this computer only.

6Printing day to day #

• Print (Ctrl+P) on a voucher follows this computer's saved setting for its voucher type. The automatic print after saving does too.
• The print options button next to Print ( Ctrl+Shift+P ) always opens the format dialog, for a one-off reprint in another format or on another printer. In Firefox, which keeps Ctrl+Shift+P for itself, use the button.
• In the format dialog: pick the format , the Printer ("Browser print dialog" or a printer of this computer) and the Copies . Then press Print (F5) , or Preview to look first.
• Tick Remember for ... on this computer and choose Silent, Ask or Preview to save the choice; it is stored when you press Print or Preview.
• A voucher printed through the agent is marked printed, exactly as a browser print is. The next print then needs the Re-print right.
• The page's status line says where the document went, for example "Sent to EPSON TM-T82".

7The agent's own settings #

The agent keeps its settings in %LOCALAPPDATA%\CLand\PrintAgent\agent.json . Right-click the tray icon -> Open settings folder . The file is created on first start.

• Port - where it listens, on this computer only (default 17888). If you change it, change the Agent address above to match.
• Token - the pairing token. Tray menu -> New pairing token... replaces it, and every paired browser then needs the new token pasted here.
• AllowedOrigins - web addresses allowed to use the agent, for example ["https://erp.yourcompany.com"] . Empty means any site may call it, but the token is still required.
• MaxPdfMegabytes - the largest document accepted (default 20).
• MaxRenderDpi - the highest resolution a page is drawn at (default 300). Higher only makes A4 pages slower (about 4 times at 600); receipt printers are not affected.
• QueueJobs - true (default) lets the ERP carry on as soon as the agent has checked the document, while the page prints in the background. false makes the ERP wait for the printer.

After editing the file, restart the agent: tray menu -> Exit , then start CLand.PrintAgent.exe again (or sign out and in).

Tray menu, in full: Copy pairing token (a double-click does the same), Show installed printers , Recent print jobs , Open settings folder , New pairing token... , Exit .

8Troubleshooting #

• "The print agent is not running on this computer" - no printer icon in the tray: start CLand.PrintAgent.exe , or run install.ps1 again. If it is running, check that the agent address above matches its Port.
• "The pairing token is missing or wrong" - copy the token again from the tray icon, paste it here and press Save Connection.
• "This web site ... is not allowed" - add the ERP's address (as shown in the browser's address bar, without a trailing slash) to AllowedOrigins, then restart the agent.
• "The printer ... is not installed on this computer" - the printer was renamed or removed. Pick it again in the table below, or from the format dialog.
• "Could not start on port ..." at start-up - another program uses that port. Change Port in agent.json and the agent address here.
• The page printed through the browser dialog instead - the agent refused the document (printer missing, unreadable PDF); the status line gives the reason. Nothing is lost.
• "Sent to ..." but nothing came out - the agent accepted the job and the printer failed afterwards (paper out, offline, driver error). The tray icon shows a red balloon; tray menu -> Recent print jobs lists each job and its error. Fix the printer and print again.
• Checking the agent itself - run CLand.PrintAgent.exe --self-test in its folder: it reports whether Windows can read and draw a PDF, and how long it takes.
• Receipt comes out tiny, huge or cut - the print format's page size should match the paper (for example 80 mm wide). A driver that ignores custom sizes shrinks the page to fit its own paper; set the paper size in the printer's preferences.
• Settings vanished - they live in this browser only: a private window, another browser, or clearing site data starts empty. Set them up again here.
• A test without paper - Test Connection only lists printers; it prints nothing.

9Removing or updating the agent #

• Remove: in the agent's folder run powershell -ExecutionPolicy Bypass -File install.ps1 -Uninstall . It stops the agent and takes it out of start-up. The settings folder is kept; delete it by hand if the token should go too.
• Update: tray menu -> Exit, copy the new files over the old folder, and start the agent again. The token and settings stay, so paired browsers keep working.
• Stop using it on one voucher type: Remove in the table above. That voucher type prints through the format dialog again.

10How it works #

• You print. The ERP checks the Print / Re-print right and the voucher status, and reads this computer's saved setting.
• The ERP server builds the document (PDF) from the chosen format, as it always has.
• The browser hands the PDF, the printer name and the copies to the agent at http://127.0.0.1:17888 . The document never leaves this computer on that step.
• The agent checks the printer and the document, tells the ERP "sent", and then draws each page with Windows' own PDF engine (at most 300 dpi) and sends it to the Windows print queue, with no dialog. Jobs are printed one at a time.

Nothing is polled: the agent sits idle until a print arrives, and the ERP only asks it for the printer list when the format dialog or this page opens (and remembers the answer for two minutes).

What is done for speed: the permission check, the status check, the saved setting and the format list are read together, not one after another; the format list is remembered for ten minutes on the direct path (the format dialog always reads it fresh); the document goes to the agent as the server sent it; the "printed" mark is written in the background; the agent answers before printing and keeps its PDF engine warm. What remains is mostly step 2, the server building the document.

Security: the agent listens only on this computer (127.0.0.1), accepts only PDF documents, and obeys only a browser that holds its pairing token (and, when set, only the allowed web addresses).

For developers: GET /health (no token) returns name and version. GET /printers returns the printers and the default. POST /print takes { printerName, copies, jobName, pdfBase64, wait } and answers { ok, pages, queued, jobId } . GET /jobs lists the last 20 jobs. POST /check takes { pdfBase64 } and renders without printing. The token goes in the X-Agent-Token header. Source: tools/CLand.PrintAgent (README.md there).

11If something does not work #