Manage label print jobs

6 min read Updated 2026-08-30 WindoorERP 19.0

What this does

Print Jobs is the audit queue between WindoorERP and your label printers. Every barcode label the system produces — from the produced-unit form, from the Shop Floor Terminal, or automatically when production starts — becomes one job here, with the rendered printer code, the target printer, and a state that tracks it from Draft to Printed. A small print agent running next to the printer polls this queue and does the physical printing; there is no IoT box involved.

The screen lives at Production › Shop Floor › Print Jobs, visible to every production user. Label layouts themselves are configured separately, under Configuration › Label Templates.

Before you start

A label template for the record type you print — the shipped Produced Unit — ZPL (4x2") covers unit labels out of the box.
For physical printing: the print agent (windoor_print_agent.py, shipped with the label module) running on a machine that reaches the printer, authenticated with the agent token an administrator sets in system parameters.

Steps

The Print Jobs queue with PRN- references, source units, format, backend, state badges — including auto-created queued jobs that carry no format yet

01
Open Production › Shop Floor › Print Jobs. Jobs arrive here on their own — from the Print Label button on produced units, the terminal's ⎙ Print Labels, or automatically at production start when the Scanning feature is on.
02
Open a job to review it: the template, the format, the Rendered Content (the raw ZPL/EPL that will reach the printer), copies and the destination fields.
03
Press Preflight to sanity-check the destination — the badge answers Ready or Needs Config with a message.
04
Press Queue on a Draft (or Failed) job to hand it to the print agent. The agent claims it (Sent to Server), prints, and reports back — the job ends Printed or Failed.
05
To print a copy of something already printed, use Reprint — it clones the job as a new draft with a Reprint Of back-link and a reason field, so the label trail stays honest.

The job form

Field	What it does
Template, Format	Where the layout came from and its language (ZPL / EPL / PDF). Read-only on the job.
Source	The record being labelled — typically a produced-unit serial.
Rendered Content	The printer code with placeholders already substituted. What you see is exactly what the agent sends.
Copies	How many labels the agent prints. Editable.
Print Backend, Printer Name, CUPS Queue, CUPS Options	Destination: Spool Folder drops a file the printer software watches; CUPS Queue runs the system print command. The CUPS fields appear only for that backend.
Print Server Target	Queue name, printer endpoint or watched-folder identifier the agent uses.
Printer Preflight, Preflight Message	The last preflight verdict: Not Checked / Ready / Needs Config, with the explanation.
Send to Print Server (button on Queued jobs)	Marks the job Sent to Server and stamps its target without waiting for an agent poll — useful for hand-off tests, but a job "sent" this way with no agent listening just sits there.
Agent Claimed At, Agent Acknowledged At, Agent Message	The agent's side of the story — when it took the job and what it reported ("Printed by external agent.", "Print agent reported a failure.").
Reprint Of, Reprint Reason	Set on jobs created by Reprint.

A printed job's form with the statusbar from Draft to Printed, the destination and agent fields, and the rendered ZPL content

How jobs are created

Produced unit → Print Label. Creates one ZPL job per selected unit from the first active produced-unit template and hands you the PDF label download at the same time — one click, both outputs.
Shop Floor Terminal. The ⎙ button on a piece, or ⎙ Print Labels on an item, creates and queues jobs for the piece or for every piece of the item.
Automatically at Start Production. With the Scanning feature on, starting a production order creates one queued job per piece that has none yet. These automatic jobs carry no rendered content and no format — visible as empty Format cells in the list — so the agent spools empty files for them unless a template fills them in later. Treat them as tracking stubs; print real labels from the unit or the terminal.

Important

Queue re-applies the template's destination. When a job has a template, pressing Queue overwrites the job's backend and CUPS queue with the template's defaults — edits made on the job are discarded at that moment. And Failed jobs are retried automatically: the agent claims failed jobs on its next poll, so a job that failed for a transient reason often fixes itself, while one failing for a real reason will flap until someone fixes the destination or deletes the job.

Troubleshooting

"Set a CUPS queue or printer name."	Preflight on a CUPS job with no queue, printer or target. Fill one in — or fix the template, since Queue copies the template's values.
Job pressed Queue but stayed Draft	Preflight answered Needs Config; queueing silently declines. Run Preflight to see the message.
Jobs sit in Queued forever	No agent is polling — it is not running, points at the wrong server, or its token does not match the `windoor_label_print.agent_token` system parameter (the agent then gets unauthorized on every poll).
The agent spools empty files	Those are the automatic jobs created at production start, which carry no content. Print the real label from the unit's Print Label button or the terminal.
A job keeps flipping Failed → Sent to Server → Failed	Failed jobs are auto-retried on every agent poll. Read Agent Message for the printer-side error and fix the destination.
"Label printing module is not installed." on the terminal	The label-print module is missing on this database; the terminal's print buttons need it.

Common mistakes

Editing the printer on a job and then pressing Queue — the template's destination wins. Change the template's defaults instead.
Using Mark Printed to tidy the queue. It only stamps the state; nothing is printed, and the audit trail now claims it was.
Deleting failed jobs to stop the retries without reading the agent message first — the next job to that printer fails the same way.
Expecting the PDF label to follow the template body. PDF output is a fixed layout; the body only drives thermal formats.
Running two agents against the same queue with different printers and no printer filter — each claims whatever it polls first, and labels come out of the wrong machine.

Was this article helpful?

Running a window or door factory?

Ask for a demo