Print agent setup: Zebra ZXP Series 7

The print agent is a small program that runs on the PC next to your card printer. The portal cannot talk to a printer directly — browsers have no path to a USB or spooler-attached device, and your printer is on your network, not the internet. The agent bridges that gap.

How it works

  Portal (cloud or your server)              Your print room
  ─────────────────────────────              ───────────────

   print job queue  ◄───── HTTPS ─────────  print agent  ──USB/LAN──►  ZXP7
        │            (outbound only)             │
        └──── card artwork (pre-signed) ────────►│
              status, ribbon counts  ◄───────────┘

The agent only makes outbound HTTPS connections. There is no inbound port, no VPN and no firewall exception to request. This is usually the difference between an integration your IT department approves and one they do not.

Before you start

• The ZXP Series 7 driver is installed and you can print a Windows/CUPS test card
• The printer is loaded with card stock and a ribbon
• You have the enrolment token, available from your organisation administrator under Settings → Integrations
• You know your organisation code (the short slug in your portal URL), or leave it blank for a bureau agent that serves all tenants

Print a test card from the operating system before installing the agent. If the OS cannot print, the agent cannot either, and you will spend an hour debugging the wrong layer.

1. Install

The usual way: download it from the portal

One self-contained file with Node embedded — nothing else to install, and no build toolchain on a machine whose job is printing cards.

Sign in to the portal, go to Settings → Downloads, and download the print agent — the page carries the full verify/unblock/enrol steps too. Put the file somewhere stable:

mkdir C:\idportal-agent; cd C:\idportal-agent

Check the download before running it — the card shows the expected digest (the download response also carries it in an X-Agent-SHA256 header):

(Get-FileHash idportal-agent.exe -Algorithm SHA256).Hash.ToLower()

The executable is unsigned, so Windows will object at up to three points — the download itself, SmartScreen at first run, and the AV. The quick clear for first run is More info → Run anyway, or once, up front:

Unblock-File .\idportal-agent.exe

The full sequence, including blocked downloads, AV quarantine and what to hand a customer’s IT department, is in Trusting the agent downloads on Windows.

Or just copy it. If the print PC’s browser refuses the download, fetch it on any machine that can and move it by hand — USB stick, share, or:

scp idportal-agent.exe printroom-pc:C:/idportal-agent/

2. Enrol this machine

.\idportal-agent.exe enrol

It asks four questions and finds your printers for you:

CardOffice print agent — setup

Portal address [https://app.cardoffice.nz]:
Enrolment token (from Settings → Integrations): ••••••••••••
A name for this machine [PRINTROOM-01 print room]: Main print room
Organisation code (leave blank for a bureau agent): your-organisation

Looking for printers…

  1. Microsoft Print to PDF
  2. ZXP Series 7
  3. HP LaserJet M404

Which one is the card printer? (number) [2]:
A label for this printer [ZXP Series 7]:

Checking the printer…
  ZXP Series 7: online — Ready

Registering with the portal…
Verifying the connection…

Setup complete.

When choosing a printer, pick the USB Card Printer driver entry rather than the “Singlesided” driver — the singlesided driver cannot do dual-sided prints.

The configuration is written to ~/.idportal-agent/config.json (on Windows, C:\Users\<you>\.idportal-agent\config.json).

The agent token in that file is a credential. Anyone with it can claim print jobs. Keep the file readable only by the account the agent runs as.

3. Run it once, by hand

This is a commissioning step, not how the agent should live. Run it from a console now to prove enrolment worked and the printer answers; then set it up to start with the machine in step 5 and stop starting it this way.

A site that installed by double-clicking has a working printer and a fragile one. The console window it opens can be closed, and closing it stops all printing at that site until somebody notices — which is usually a person standing at a counter with a queue.

.\idportal-agent.exe

09:14:02 INFO  print agent starting {"version":"2.0.0","printers":["ZXP_Series_7"]}
09:14:03 INFO  card printed {"jobId":"8f2c…","card":"Alice Johnson (STU-2026-0041)","seconds":24.1}

Check it any time without printing anything:

.\idportal-agent.exe status

4. Test without wasting cards

Set "dryRun": true in config.json. The agent runs the full pipeline — claim the job, download artwork, report success — without sending anything to the printer. Artwork is saved in the spool directory so you can inspect it.

To produce a test job, go through the portal:

1. Ensure a card holder exists with an approved photo
2. Create an order containing that holder and submit it
3. Go to Production → New print run, add the order, and release the run
4. The agent claims the job within seconds

Set "dryRun": false (or remove the key) when you are ready to print for real.

5. Run it automatically

This is how the agent should be installed. Not an optional extra for tidy sites — it is the difference between an agent that survives a reboot and one that stops when somebody closes a window. Pick the option for your OS.

Beyond starting at boot, it fixes two things the console does not:

• The process runs non-interactively, so there is no window for anyone to close, and none of the PowerShell queries the agent makes can flash one up.
• It restarts on crash, so a fault does not need a person to notice it.

Windows — a scheduled task

Run in an administrator PowerShell. Adjust the path to match where you put the executable:

$action  = New-ScheduledTaskAction -Execute "C:\idportal-agent\idportal-agent.exe"

$trigger = New-ScheduledTaskTrigger -AtStartup
$principal = New-ScheduledTaskPrincipal -UserId "$env:USERDOMAIN\$env:USERNAME" `
               -LogonType S4U -RunLevel Limited
$settings  = New-ScheduledTaskSettingsSet -RestartCount 999 -RestartInterval (New-TimeSpan -Minutes 1) `
               -ExecutionTimeLimit ([TimeSpan]::Zero)

Register-ScheduledTask -TaskName "CardOffice print agent" `
  -Action $action -Trigger $trigger -Principal $principal -Settings $settings

Run it as the account that owns the printer connection, not as SYSTEM — SYSTEM often cannot see per-user printer queues.

-LogonType S4U is the part that makes it windowless: the task runs without an interactive session, so neither the agent nor anything it starts can put a window on someone’s screen. -RestartCount 999 is what brings it back if it dies. Keep both.

Why not NSSM or WinSW? Both give real service semantics and both were considered. Both put a second third-party binary into every print room, and the person installing it works for the customer’s IT department, not for us. Task Scheduler already does start-at-boot, non-interactive execution and restart-on-crash. Revisit only if a site needs service dependencies or a start order Task Scheduler cannot express.

Linux — a systemd service

/etc/systemd/system/idportal-agent.service:

[Unit]
Description=CardOffice print agent
After=network-online.target cups.service
Wants=network-online.target

[Service]
Type=simple
User=printroom
ExecStart=/usr/bin/node /usr/lib/node_modules/@idportal/print-agent/dist/index.js
Restart=always
RestartSec=10
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now idportal-agent
sudo journalctl -u idportal-agent -f

macOS — a launchd agent

~/Library/LaunchAgents/nz.secureid.idportal-agent.plist, then:

launchctl load ~/Library/LaunchAgents/nz.secureid.idportal-agent.plist

Printer settings that matter

Set these in the ZXP7 driver’s printing preferences. The agent uses the driver’s saved settings, so getting these right once fixes every job.

Setting	Value	Why
Card size	CR-80 (85.6 × 53.98 mm)	The artwork is rendered to exactly this
Orientation	Landscape	Matches the default template
Print resolution	300 dpi	The ZXP7’s native head resolution
Colour correction	Off / None	The artwork is already colour-managed to sRGB. Leaving driver correction on is what makes skin tones go orange.
Print both sides	On, if your template is double-sided
Ribbon type	Match what is fitted	Drives the panel sequence
Rotate front / back 180°	As your card stock requires

Ribbons

Ribbon	Images per roll	Good for
YMCKO	750	Colour front, blank or pre-printed back
YMCKOK	500	Colour front, black text or barcode on the back
YMCUvK	750	Colour with a UV security panel
K (monochrome)	5000	Text-only cards, or pre-printed stock
KdO	1500	Monochrome with a protective overlay

Yields are the published figures and are used as defaults for the consumable counter. Check the number on your ribbon box and correct it in Production → Consumables if it differs.

A double-sided card on a YMCKO ribbon costs two images, not one — the back needs a second pass. On YMCKOK it costs one. This is the difference between a ribbon lasting a week and lasting three days, and the portal counts it correctly for whichever ribbon you have fitted.

Magnetic stripe encoding

If your template has magnetic stripe encoding turned on, the agent sends the track data along with the print job.

On Linux/CUPS this goes through the Zebra CUPS driver’s options. If your driver build names them differently, override them in config.json:

{
  "printers": [
    {
      "queueName": "Zebra_ZXP_Series_7",
      "displayName": "ZXP Series 7",
      "driverOptions": {
        "zebra-mag-track1": "",
        "ZebraMagCoercivity": "High"
      }
    }
  ]
}

On Windows encoding goes through Zebra’s own utility. Point the agent at it:

[Environment]::SetEnvironmentVariable("ZEBRA_ENCODER_PATH", "C:\Program Files\Zebra\encoder.exe", "Machine")

If encoding is required and the utility is missing, the agent fails the job rather than printing an unencoded card — a card that looks right but does not open a door is worse than one that never printed.

Track limits are enforced before printing (ISO 7811): track 1 up to 76 alphanumeric characters, tracks 2 and 3 numeric only, up to 37 and 104.

Configuration reference

~/.idportal-agent/config.json:

Key	Default	Meaning
serverUrl	—	Your portal address
agentToken	—	Issued at enrolment. Treat as a password.
agentName	hostname	Shown in the production console
printers[].queueName	—	The OS print queue name
printers[].displayName	—	Label shown in the portal
printers[].driverOptions	{}	Passed straight to lp / the spooler
pollIntervalSeconds	5	How often to check for work when idle
heartbeatIntervalSeconds	60	How often to report status
proactiveWake	false	Keep the printer awake instead of letting it sleep. See below.
spoolDirectory	~/.idportal-agent/spool	Where artwork is staged
keepArtworkHours	48	How long staged artwork is kept
logLevel	info	debug when diagnosing
dryRun	false	Stage the files but do not print

dryRun is the setting to reach for when commissioning a new site. It runs the whole pipeline — claim, download, report — and leaves the artwork in the spool directory so you can open it and check it, without consuming a card.

proactiveWake — letting the printer sleep

The ZXP7 goes into standby by itself, and when it does Windows marks the queue Use Printer Offline. That mark is set by Windows, not the printer, and it does not clear when the printer wakes — so jobs pile up in the spooler and the card that would have woken the printer never reaches it.

The agent deals with this in one of two ways.

	proactiveWake: false (default)	proactiveWake: true
While idle	The printer is left alone and sleeps. Its status is checked every ten minutes rather than every minute, because the status check itself would keep it awake.	The queue is cleared the moment the agent sees it held, at most every five minutes.
In the portal	Reads Online, with Standby — asleep until the next card	Reads Online
When a card arrives	The queue is cleared first, so the first card after a quiet spell takes a few seconds longer	Already awake
An unplugged printer	Reads as standby until its first card fails	Shows as offline within a minute

Choose true where somebody watches the console and needs an unplugged printer to show up immediately. Leave it alone otherwise.

Upgrading from 2.0.0 changes this. Agent 2.0.0 always woke the printer, which is what true now means. Leaving the new default in place means a printer that used to stay awake will start sleeping. Set proactiveWake: true in config.json to keep a machine behaving the way it did.

The portal can override this per printer, on the printer’s page under Printer settings → Wake mode. A choice made there wins over config.json and takes effect on the next check-in, within about a minute. Setting it back to use the print PC’s setting hands the decision to this file again. Prefer the portal: it is visible to the people who notice the problem, and it does not need anyone to log on to the print PC.

Confirm what a machine is actually doing without opening the file:

.\idportal-agent.exe status

  Dry run       no
  Wake mode     on demand — the printer may sleep

That reports this file’s setting. Where the portal has overridden it, the agent logs the change at startup and whenever it changes.

What the agent does about failures

Situation	What happens
Portal unreachable	Retries with backoff, up to a minute between tries. Prints resume by themselves.
Printer asleep	Nothing to do. It shows as Standby — asleep until the next card, and the queue is woken when a card arrives. The first card takes a few seconds longer.
Windows latched the queue offline	Cleared automatically — before the card is printed, or on every heartbeat with proactiveWake: true. It no longer needs anyone to clear it by hand.
Printer offline	Job reported failed, requeued automatically.
Printer unplugged, proactiveWake: false	Reads as standby until a card is sent and fails, then reports offline properly. Set proactiveWake: true if a site needs this noticed sooner.
Out of cards or ribbon	Job parked as failed and the operator is told. Not retried — someone has to open the printer.
Card jam	Same: parked, with the jam reported in the console.
Encoding failed	Job fails. No unencoded card is produced.
Agent crashes mid-print	Its lease expires after 5 minutes and the job is requeued for another agent.
Agent stops checking in	Marked offline after 3 minutes; operators are emailed.

The agent renews its lease every 30 seconds while a card is printing, so a slow double-sided card with encoding is never handed to a second agent.

Troubleshooting

“No agent configuration found” — run idportal-agent enrol.

“That agent token is not recognised” — the agent was deleted in the portal. Enrol again.

“This agent has been deactivated” — someone turned it off in Production → Print agents. Re-enable it there.

Nothing prints, no errors — check idportal-agent status. If the portal connection is OK and the printer is online, look at the print queue: there may be nothing queued, or the cards may not have finished rendering.

Cards print but the colours are wrong — driver colour correction is on. Turn it off; the artwork is already colour-managed.

Cards print off-centre or scaled — the driver is scaling to fit. Set the card size to CR-80 and disable any “fit to page” option. The artwork already includes bleed.

Only the front prints on a double-sided template — the driver is set to single-sided, or a YMCKO ribbon is fitted where the design needs two passes.

Windows: “Access is denied” — the agent is running as a user who cannot see the printer. Run it as the account that installed the printer.