# Printing & the print agent

> Silent thermal printing driven by printers, print rules, a print queue and a branch print agent.

Source: https://sofra.tablixai.com/docs/printing

Section: Run service

Sofra prints kitchen, bar, pickup, packing and cancel tickets. **Manual printing** of bills, receipts and kitchen tickets works on every plan. **Automatic printing** (printers, rules, the print agent and the print queue) is available from Pro.

> **Available on Pro and above:** Automatic printing needs Pro. Station-based rules also need Prep Workflows. Station-move tickets and course or order-source routing need Pro Plus.

## How it fits together

```text
Order action  ->  Print event  ->  Print rule (when / what / where)  ->  Print job (queue)  ->  Printer
                                                                          |
                              browser Print Queue page  OR  print agent on the branch PC
```

- **Printers** are the hardware at a branch.
- **Print rules** say *when* something prints, *what* document, on *which printer*, and how many copies. **Rules start switched off**; nothing prints automatically until you create and enable one.
- **Print jobs** are queued with a frozen copy of the data, so a retry or reprint never depends on the live order and a retry can never print two copies.

## Add a printer

Go to **Settings → Printers** and choose **Add Printer**.

| Field | Options |
|---|---|
| Name | For example “Kitchen” or “Bar”. |
| Type | Thermal receipt, label, A4/office or virtual (PDF/testing). |
| Paper size | 58 mm, 80 mm, A5 or A4. |
| Connection | **Browser queue** (a device with the Print Queue page open), **Network printer via print agent** (IP address and port, usually 9100), or **USB / Windows printer via print agent** (the printer’s name on the agent PC). |

Use **Test print** to send a sample ticket and confirm the printer is wired up. Network and USB printers report **online/offline** status through their agent. Deleting a printer disables any rules that pointed to it, so nothing queues for a printer that no longer exists.

## Print rules

Go to **Settings → Print Rules**. Each rule has:

| Part | Details |
|---|---|
| Name | Your label. |
| When this happens (trigger) | Item sent to kitchen, order ready, pickup ready, packing required, item voided, order cancelled, item moved between stations, or manual reprint. |
| Filters | Station(s) or station type(s), order type, order source, course numbers, and “items with no station only”. |
| Print (document) | Kitchen ticket, bar ticket, prep ticket, pickup ticket, packing slip, delivery slip or cancel ticket. |
| Template | A specific template, or the default for that ticket. |
| On printer | One of this branch’s printers. |
| Copies | 1 to 5. |
| Tickets | **One per station** (the whole order if no stations) or **one per order**. |

Typical setup: a rule “Kitchen tickets” that prints a kitchen ticket when items are sent, for the Grill station, on the kitchen printer; and a rule “Bar tickets” for drinks on the bar printer. Turn each rule on when ready. If a plan is downgraded the rules are kept but stop firing.

### When each trigger fires

| Trigger | Fires when |
|---|---|
| Item sent | Items are sent to the kitchen (including automatically when an order is confirmed). |
| Order ready | The order becomes ready. |
| Pickup ready | A takeaway order becomes ready for pickup. |
| Packing required | A delivery order becomes ready and needs packing. |
| Item voided / Order cancelled | Something already sent is cancelled; a cancel ticket tells the kitchen on paper. |
| Item moved | An item passes to another station (Pro Plus). |
| Manual reprint | Someone presses Reprint. A reprint always creates a new job. |

## Print queue

**Operations → Print Queue** shows recent jobs and their status: queued, printing, printed, failed or cancelled. On a device serving browser-queue printers, choose **Start printing** to let that device pick up and print jobs, and **Pause printing** to stop. From the queue you can **retry** or **cancel** jobs, subject to permission. Claims that are never acknowledged are offered again after a short timeout.

## The print agent

To print **silently** on network and USB printers, install the print agent on a PC in the branch (Windows recommended). It polls Sofra over HTTPS, so no inbound ports are needed.

```text
Sofra (cloud)  <-- HTTPS --  Print Agent (branch PC)  -- TCP :9100 / USB -->  Thermal printer
 print rules + queue          render ticket -> image -> ESC/POS
```

Tickets are rendered from your template by Edge or Chrome and printed **as an image**, so what comes out matches the on-screen preview exactly, including right-to-left languages such as Urdu and Arabic.

1. **Install prerequisites.** Install Node.js 20 LTS. Microsoft Edge or Chrome must be installed (Edge ships with Windows).
2. **Install the agent.** Copy the `print-agent` folder to the PC, for example `C:\SofraPrintAgent`, and run `npm install`.
3. **Create the agent in Sofra.** Go to **Settings → Printers → Print agents → Add agent**. Copy the configuration shown into `config.json`. The token is displayed **once**; only a hash is stored. You can **rotate** it later or **revoke** it, which stops it working immediately.
4. **Check the connection.** Run `npm run check`. You should see that it connected to Sofra as your agent and probed each printer.
5. **Add your printers.** In Sofra choose **Add Printer**, pick *Network printer via print agent* or *USB / Windows printer via print agent*, select the agent, and press **Test print**.
6. **Run it.** Run `npm start`. To start with the PC, use Task Scheduler (trigger: At startup) or install it as a service with NSSM.
7. **Create print rules.** Add and switch on the rules that decide what prints where.

```bash
npm install
npm run check   # verify the token and probe printers
npm start       # run the agent
```

### Agent commands

| Command | What it does |
|---|---|
| `npm start` | Run the agent. |
| `npm run check` | Verify the token and connection and probe every printer. |
| `npm run once` | Print at most one queued ticket, then exit (good for testing). |
| `npm test` | Run the unit and end-to-end tests with a fake printer. |

### config.json

| Key | Meaning |
|---|---|
| apiUrl, tenant, token | Provided by Sofra when you create the agent. |
| browserPath | Optional path to Edge or Chrome; auto-detected otherwise. |
| pollSeconds / heartbeatSeconds | How often to look for tickets and report status (defaults 2 and 20). |
| printers | Optional per-printer overrides keyed by the printer name in Sofra: `dots` (576 for 80 mm, 384 for 58 mm), `cut` (full, partial, none), `feedLines`, `drawer` (open the cash drawer after the ticket), `dither`, `threshold`. |

> **Note:** Each agent is bound to **one branch** and can only see and claim jobs for the printers assigned to it.

## Permissions

Printing has its own permissions: `printing:view`, `printing:print`, `printing:reprint`, `printing:manage_printers`, `printing:manage_rules`, `printing:view_jobs`, `printing:retry_jobs` and `printing:cancel_jobs`. Managers and branch managers have them all; kitchen staff can view jobs, print and reprint.