Printing & workplaces
Overview
Four surfaces carry label printing between them:
| Surface | What it answers |
|---|---|
| Workplaces | where printing and weighing happen — and whether an agent is running there |
| Printers | which device sits at which workplace and what it accepts |
| Label templates | what appears on item, shelf and batch labels |
| Print jobs | what is queued at the devices — and what went wrong there |
The sentence explaining the most common fault appears in the application itself: without a registered printer there is no direct printing. The agent at the workplace is the link between system and device; if it is not running, jobs pile up that nobody prints.
Core tasks
Set up workplaces. One per place where printing or weighing happens. The display states whether an agent is running there.
Register printers. Device, workplace and the accepted formats.
Maintain label templates. One template per thing — item, shelf, batch. Batch labels draw on the data from batches and serial numbers.
Check print jobs. The list shows what is queued and what failed. It is the first place to look on a fault — not the printer.
Sending documents: the output channels
Quotes, orders and invoices leave the house through one dialog, Send document. Under Output channels the ways can be combined; each way leaves a trace on the document (channel, recipient or target, copies, time, result).
- Send by e-mail — to one or more recipients, with subject, cover text, further attachments from
the file store and, if wanted, a copy to yourself; each recipient gets a delivery of their own.
- Print — the document PDF goes into the print queue of a workstation, with the number of
Copies. Which printer it ends up on is decided by the document types on the printer (see below, e.g. invoice for invoices). Without a configured workstation the way is switched off and says why: "No print workstation configured."
- Send with the goods — nothing is sent: the document is earmarked as an enclosure for the
order's next shipment, its PDF frozen in the process. What belongs in the box is shown under Shipping centre → Shipments → Enclosures. Documents without goods do not offer this way.
Print enclosures at the packing station. To have earmarked enclosures come out of the printer by themselves when packing, there is the shipped flow Beilagen am Packtisch drucken (print enclosures at the packing station): when a shipment is booked it prints all enclosures of that order. It is off by default and is switched on under Settings → Shipping in the card Shipping flows. The card lists all flows that listen to the booking of a shipment, with trigger and state; New flow and Open in automation editor lead to automations — a shipping flow is a normal automation. Conditions such as carrier, destination country or weight are added there, for instance "only for DHL to Austria".
Fixed enclosures. Files that should always go along (terms and conditions, cancellation policy) are attached once per document type and brand under document attachments. In the dialog they appear as always attached and can be removed for this one dispatch.
Recipient rules per customer. On the customer, in the Contacts tab, the section Document recipient rules decides who a document of this customer is proposed to — per document type (quote, order, invoice) or for All document types. The recipient is determined either by contact role (bookkeeping gets the invoice; if the person changes, the recipient changes with them) or by a fixed address. On top come Copy to addresses and Also print — the document then goes by e-mail and to print, provided a print workstation exists. A rule for one document type beats the one for all; there is exactly one rule per document type. The rule adds to the dialog: addresses chosen by hand take precedence, and without a rule shipping proposes the main contact. If nobody at the customer holds the chosen role, the rule does not apply — the list points this out.
Fields in detail
Resolution (dpi) on printer and label template: 203 (default) or 300 dpi. A ZPL template must match the printer's resolution or it prints distorted; for PDF templates the field stays empty.
The What it does column answers what changes in the system — not what the field is called. The grey name behind it is the API field: the same thing runs under that name through automation, import and AI tools.
Workplace
| Field | Required | Values / format | What it does |
|---|---|---|---|
Key workplaceKey | yes | text, lower case, e.g. packing-bench-1 | How the local agent signs in — the same key sits in its configuration. It is the identifier in jobs and reports. |
Name name | yes | text | What the workplace is called in the list — usually the place, say "packing bench 2". |
Active active | no | yes/no | Whether the workplace receives jobs. |
Brand brandId | no | one of your brands | Which brand the workplace works for. Changing the brand invalidates the agent token: the workplace stays silent until a new one is issued. The response says so explicitly. |
The device token is deliberately not a field but an action of its own: every issue invalidates the previous one, and the plain text exists exactly once — in the response of the issuing call. After that the list shows only a recognition prefix. A token sees only this workplace's jobs.
Printer
| Field | Required | Values / format | What it does |
|---|---|---|---|
Workplace workplaceUlid | yes | existing workplace | Where the device stands. |
Device key printerKey | yes | text, the operating system's queue name, e.g. ZDesigner-GK420d | The name under which the agent knows the device. Get it wrong and the agent does not find the printer. |
Name name | yes | text | What the device is called in the picker. |
Format format | yes | zpl or pdf | What the device accepts. Label printers speak ZPL, office printers PDF. |
Document types documentTypes | no | list, e.g. shipping_label, delivery_note; empty = all | The actual routing: that is how the shipping label goes to the label printer and the delivery note to the A4 printer without anyone choosing. Empty means "takes everything" — the single-printer case runs without configuration. |
Default isDefault | no | yes/no | Which device is taken when several fit. |
Active active | no | yes/no | Whether the device receives jobs. |
Label template
| Field | Required | Values / format | What it does |
|---|---|---|---|
Subject subjectType | yes | product, bin (shelf location), batch | What the template is for. Every subject brings its own placeholders; the list sits above the table. |
Key templateKey | yes | text, e.g. product-ean-50x30 | The identifier of the template. Fixed once created — and the lever for superseding a shipped template: your own one with the same key wins. |
Name name | yes | text | What the template is called in the picker. |
Body body | yes | ZPL with placeholders of the form {{ variable }} | What is on the label. An unknown placeholder is rejected in plain words on save — not first at print time. |
Width widthMm | no | number in millimetres | The label width. |
Height heightMm | no | number in millimetres | The label height. |
Default isDefault | no | yes/no | Which template is taken for this subject without further choice. |
Active active | no | yes/no | Whether the template is offered. Created through the interface it is active; retiring one is a route through API and automation. |
The list also shows the shipped templates. They live in the code and have no database row; hiding them would mean administration reports "no templates" while the system prints.
Print job
A job arises from an action — print a label, output a document — and from automation and the API. On this page it is not created but watched, cancelled and reprinted.
| Field | Required | Values / format | What it does |
|---|---|---|---|
Workplace workplaceKey | yes | key of a workplace | Where it is printed. |
Document type documentType | yes | text, e.g. shipping_label | What is printed. The registry looks for the matching device by it. |
Format format | yes | zpl or pdf | Which language the payload is in. |
Payload payload | yes | ZPL text or base64-encoded PDF | The print content. It is never read back — a label carries the recipient address and the tracking number, and the queue is an operations view, not a document archive. Whoever needs the label fetches it at the document. |
Copies copies | no | number | How many copies. |
Device printerKey | no | key of a printer | An explicitly requested device. Without it the registry decides by document type and format. |
| Element | From | What it means |
|---|---|---|
| Status | the agent's feedback | Queued, claimed, printed, failed or cancelled. A failed job stays and is not silently discarded — otherwise a label would be missing without anyone noticing. |
| Error reason | the agent's feedback | Why it went wrong. Often a format the printer does not accept. |
| Cancel | action | Only while no one has claimed the job yet. |
| Reprint | action | Sends the same job again. For numbered documents no new number arises. |
| Scale | agent at the workplace | Weight in grams and whether the value is stable. Display only — there is nothing to type in; a stale value is not shown at all. |
Settings & permissions
- Module
module.print. print.workplace.view/.managefor workplaces and printers,print.job.view,
.create, .manage for jobs.
- The agent runs at the workplace, not in the browser. It is the precondition for direct printing.
- Output channels: the dialog offers Print as soon as an active workstation exists; recipient
rules are maintained by whoever may edit the customer (API /api/v1/customers/{ulid}/document-dispatch-rules).
- Shelf labels match the bins from multi-warehouse.
FAQ & troubleshooting
Nothing is printed. Check in this order: is the agent running at the workplace? Is a printer registered? Does it accept the format? Only then the device itself.
A print job shows as failed. The list names the reason. Often it is a format the printer does not accept.
The label shows the wrong details. Check the template — there is one per thing.
Batch labels are empty. Then the item is not set as requiring proof, see Batches.