Print Queue
The Print Jobs page shows all print jobs of the Print Service with their current status, newest first. From here you can retry failed jobs, cancel jobs and process the queue right away.
Opening the Page
- Via search: Print Jobs
- Via the Dashboard → Print Jobs or by clicking a tile (e.g. Open print jobs, Failed – with a matching filter)
- Via the printer card → Print Jobs (filtered to the printer)
Fields
| Field | Description |
|---|---|
| Entry No. | Sequential number of the print job |
| Status | Current status (see status overview) |
| Document Type | Type of document: Shipping Label, Report or Raw Document |
| Document Name | Name of the printed document, for reports the report name |
| Document No. | Related document number (e.g. posted shipment) |
| Printer Code | Printer the job is/was sent to |
| Location Code | Location of the document; for shipping labels the location of the sales order. The routing rules match against it |
| Print Method | PDF or ZPL |
| Provider Code | Shipping provider (shipping labels only) |
| Tracking No. | Tracking number of the shipping label (shipping labels only) |
| Copies | Number of copies |
| Created At | Time of creation |
| Completed At | Time the job was printed, failed or cancelled |
| Retry Count | Retry attempts so far |
| Error Message | Last error message |
| Created By | User who triggered the job |
Status Overview
| Status | Description |
|---|---|
| Pending Render | A report from posting has been queued. An immediate print task renders it seconds after the posting – never during the posting itself – and then sets the job to Queued. Whatever no task reaches is rendered by the next print queue run |
| Queued | Waiting to be sent (new jobs, or jobs waiting for the next retry) |
| Sending | Being transmitted, or with Relay/Poll being processed by the Function or the agent |
| Printed | Printed successfully |
| Failed | An error that retrying cannot fix, or all retries used up |
| Cancelled | Cancelled manually |
Actions
| Action | Description |
|---|---|
| Retry | Puts the selected failed job back to Queued; retry count, error message and Completed At are reset. Immediate printing sends it seconds later |
| Retry All Failed | Puts all failed jobs back to Queued; immediate printing sends them seconds later |
| Cancel | Cancels the selected jobs (status → Cancelled). Possible for Pending Render, Queued, Sending and Failed. Select several lines to cancel them in one go: a confirmation names the number and how many of them have already been sent, printed and cancelled jobs are skipped, and a summary shows the result. For a single line, BC only asks for confirmation with Sending, because the print service may still print the job |
| Process Queue | Runs the print queue now: renders the reports from posting, returns hanging direct push jobs and sends all due jobs. The same run as on the Dashboard and in the Print Service Settings |
Immediate printing
Every new print job – from a posting, a shipping label, printing by hand or a retry – starts a background task that renders and sends it seconds after the commit. You therefore only need Process Queue when required – for example when the print queue's job queue entry is not scheduled and retries are left waiting.
Retry Logic
- If sending fails (no connection, timeout, server error), the Retry Count is increased and the job is sent again after the Retry Delay (Seconds). Once the Max Retry Attempts from the Print Service Settings are exceeded, it becomes Failed.
- If the print service or the Function answers with an error that a retry cannot fix (HTTP 4xx except 408 and 429, e.g. wrong API key or unknown printer), the job becomes Failed immediately; with HTTP 401 the printer is additionally set to Error.
- If a report cannot be rendered, the print queue tries up to five times; after that the job becomes Failed.
- A direct push job that has been Sending for more than 10 minutes without an answer is returned to the queue under the normal retry rules.
- A manual Retry is possible at any time.
Relay and Poll
With Relay and Poll, a job stays Sending after it has been handed to the queue until the agent reports the result – also overnight when the machine is switched off. Without any report it is set to Failed after 25 hours.
Printing labels manually
If auto-print is switched off or a label should be printed again:
- Open the Shipment Labels list and select the labels.
- Choose Print Label (several labels) or Reprint Label (print the selected label again).
- In the Select Printer dialog, choose the printer and the number of Copies.
The jobs then appear in the print queue.
Common Errors and Solutions
No connection to the print service
Cause: MC.PrintService not reachable. Solution: Check that the service is running and that the Service URL on the printer card is correct. Then run Test Connection.
HTTP 401
Cause: API key missing or not matching the print service (with Relay: wrong Relay
Function Key).
Solution: On the service machine, put the API key on the clipboard with Copy in the
configuration UI http://localhost:5049/config (in BC: Open Local Configuration) – it is
never shown – and paste it again in the API Key field on the printer card.
Printer not found
Cause: The Printer Name does not exist on the machine that received the job. The
message "Printer … is not installed on the print service machine http://localhost:5049/config lists all installed Windows
printers. Enter the name exactly as shown. When several computers print via Relay/Poll, check
the Agent field on the printer card: it must name the computer the printer is installed
on.
No queue for print agent …
Cause: The printer names a computer in the Agent field for which the Azure deployment
has no queue. The job fails at once.
Solution: Add the name to the parameter agentNames and deploy the template again (see
Installation – Several computers), then Retry. If a
single computer prints everything, clear the Agent field.
ZPL printer not reachable or not allowed
Cause: The Zebra printer does not answer via TCP/IP, or its address or port is outside the allowed print targets (private networks, ports 9100–9103 and 6101). Solution: Check the network connection, IP address and port, and use the ZPL test in the configuration UI. Other networks or ports: MC.PrintService – Reference.
Job hangs in "Sending" (Relay/Poll)
Cause: Agent offline, wrong listen connection string, or outbound connection blocked. With
several computers: no service reads the agent's queue because the computer's
Relay:QueueName does not match the printer's Agent field.
Solution: Check the service on the machine, verify Relay:Enabled and the connection
string, allow outbound port 443 to *.servicebus.windows.net. With several computers, set up
Relay:QueueName = print-jobs-<agent> with the listen connection string of that queue.
Notes
Cleanup
Printed and cancelled jobs older than Log Retention (Days) are removed by the Cleanup Old Jobs action in the Print Service Settings. Failed jobs stay until they are retried or cancelled.