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.
Fields in detail
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.
- 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.