Encoder agent setup

The encoder agent runs the door-access encoding station: scan a printed card, confirm the face, write the chip. It is only for sites that encode door access onto their cards; most sites do not need it.

What it does

Encoding is a separate step from printing, at its own station. The operator scans the barcode printed on a card. The station looks the person up in CardOffice and shows their photo and card details; the operator checks the face matches the card in hand, places it on the reader, and presses Enter. The station writes the door-access credential to the chip, reads it back to check it, and reports the result to CardOffice. Every attempt, successful or not, is on record.

Like the print agent, it only makes outbound HTTPS connections: no inbound firewall rule, and no database connection on the station. Your door system’s site keys are held encrypted on the station itself and never pass through CardOffice.

What the station needs

The download is not the whole installation.

1. A supported contactless card reader, with its driver installed and the reader visible in Device Manager.
2. Your door system vendor’s encoding library, installed from the vendor’s own package. CardOffice does not supply it. Run the vendor’s installer to its default location; on first launch the encoder agent finds the library and offers to register it, with one administrator prompt.
3. A barcode scanner that types like a keyboard and sends Enter after each scan (most do, out of the box).

The agent checks the library each time it starts. If it cannot load it, a red banner says so, the station reports the problem to CardOffice (visible to administrators), and nothing can be encoded until it is fixed.

Install, enrol, and load the site keys

1. Download the encoder agent from Settings → Downloads in CardOffice and check the SHA-256 shown there. Put it somewhere permanent and make a shortcut.
2. Make it open at sign-in. It is a desktop app an operator uses, not a background service, so it starts when the operator signs in rather than at boot. Put the shortcut in the Startup folder: press Windows+R, type shell:startup, and copy the shortcut into the folder that opens.
3. The first launch asks to enrol: the CardOffice address, an enrolment token from your administrator, and a name for the station. The station proves its new credential at once and stores it encrypted, locked to that PC.
4. An administrator loads your door system’s site keys once per station, from a file your door system administrator provides, then deletes the plain file. The encrypted copy cannot be moved to another PC.

PINs are off by default

The station’s PIN setting is off by default. Do not turn it on without checking with your door system administrator: a wrong PIN setting is not caught by the read-back check, so a card can pass and still fail at the door.

The operating rhythm

Two presses of Enter per card, and the border colour shows where you are.

1. Scan the card’s barcode. A scan works from any idle state; the app sends it to the right box wherever the focus is.
2. Look. The person’s photo and details appear. Check them against the card in your hand. Inactive or expired card holders show a clear warning; you decide.
3. Enter, with the card on the reader. A green flash and a chime mean the card is encoded and checked, and the screen resets for the next card.

Grey is ready, blue is working, amber is waiting for you to confirm, green is done and checked, and red means stop. Escape cancels at any point. A red result means void that card and use a new one; the reason and an error code for support are on the screen.

Working on the same PC as CardOffice

• Encode card from CardOffice. On a card holder’s page, Encode card passes their barcode straight to the encoder agent: its window comes to the front with the person already looked up, so you check the face and press Enter. Only one encoder window runs on a PC; opening it again brings the first one forward.
• Keep on top. The pin in the encoder’s header keeps its window above the browser, so a scan or a click never lands in a hidden window.
• Scanning still works from anywhere in the encoder: if the scanner starts typing while another part of the window has focus, the characters go to the barcode box and a new cycle starts.

How long the green confirmation stays

After a successful encode, the confirmation either clears itself after a number of seconds (4 by default) or stays until the operator clicks Done, next card or scans the next card. Set it in appsettings.json beside the encoder agent:

{ "Confirmation": { "Mode": "timed", "Seconds": 8 } }

holds it for 8 seconds, and

{ "Confirmation": { "Mode": "manual" } }

holds it until clicked. Restart the app to apply the change.

If something goes wrong

What you see	What it means
“Portal unreachable” banner	The station has lost its network path. Lookups and result logging fail until it returns
Library not registered banner	If the banner offers Register, click it and approve the administrator prompt. No button means the vendor’s package is not installed; run the vendor’s installer first
“No record found” on a valid card	The person has no barcode on their CardOffice record yet, or your data sync has not delivered it
“More than one card holder has this barcode”	Duplicate data. Do not encode; ask an administrator to sort it out
Encoded, but “result could not be logged”	The card is fine; CardOffice did not receive the event. Note the card and tell an administrator

For anything else, contact support with the error code on the screen.