Chapter 40 — Biometric devices

A fingerprint terminal at the door is the most common answer to "how do we know who was in", and the least glamorous part of an HR system to run: a box on the wall with its own clock, its own list of people, and its own idea of what a punch is. Operentra talks to ZKTeco terminals directly, pulls their punches into attendance, and gives HR the controls that otherwise need a technician at the keypad. This chapter is the whole life of a device, from the wizard to the night its clock jumps to 2103.

This chapter needs the Biometric plan feature; on a plan without it the menu entry is locked.

What this chapter covers

• 40.1 Adding a device with the detection wizard
• 40.2 Device detail and storage
• 40.3 Syncing: auto-sync, sync now, fetch latest, fetch all
• 40.4 Device users: bind, unbind, edit, delete, identify a person
• 40.5 Fingerprint enrolment from Operentra; pulling fingerprints
• 40.6 Pushing employees to a device
• 40.7 The punches page and unmapped punches
• 40.8 Sync history and flushing stuck jobs
• 40.9 Device controls: time, date format, power, LCD, voice, network, danger zone
• 40.10 Command log
• 40.11 Device backups and restore
• 40.12 Device-clock problems and what to do

The concept

A terminal is a second system of record with three lists of its own: users (a numeric ID, a name, a card, a role, a password), templates (the fingerprints or faces enrolled against those IDs), and the attendance log (every scan, stamped by the device's clock). Nothing on it knows what an employee is. Integration is therefore three jobs that never end: keep the device's users mapped to your employees, keep pulling its log and turning scans into days, and keep the device itself healthy, which mostly means its clock, its storage and its power.

Two disciplines matter more than any feature. Bind before you trust: a scan from an unmapped device user is a fact about a number, not a person, and must wait. Back up before you touch: every write to a terminal is irreversible from its side, and a fingerprint database lost to a bad restore is weeks of re-enrolment.

How Operentra handles it

• Attendance › Biometric Devices lists each terminal with its vendor, endpoint, firmware, user and log counts and last-seen time, and the actions Test connection, Sync now, Details, Disable or Enable, Edit, Remove. The vendor today is ZKTeco (the ZK protocol over TCP or UDP, port 4370 by default).
• Adding is a two-step wizard: Connect probes the address and shows what answered (model, firmware, serial, name, users, logs), then Details names it, sets the area, auto-sync interval, timeouts, the IN/OUT rule and the clear-after-sync switch.
• Three pulls: auto-sync every N minutes for devices whose log count changed; Fetch Latest, the same fast path by hand; Fetch All, a full buffer pull that bypasses the gate.
• Merging groups a day's scans per device user, takes the first as IN and the last as OUT (or the device's own flag when switched on), grades the day with the usual rules, and never overwrites a regularized, Forced, leave, holiday or weekend day. Scans from an unmapped user wait as unmapped; scans from someone on an exempt shift are logged and discarded; scans stamped more than a day in the future are quarantined as a device clock fault.
• Device users are bound to employees, singly with suggestions or in bulk; binding reassigns the historical punches. Users can be edited, deleted from the device, or identified by a live scan.
• Fingerprints can be enrolled from Operentra (the device goes into enrolment mode, the person scans three times) and pulled into a per-employee library, which travels with the employee to a new device or back after a rejoin.
• Push Employees creates device users for selected employees with the next free numeric ID; fingerprints are still enrolled at the device.
• Controls push the server's time, the date format, enable, disable, restart, power off, write to the LCD, test the voice, silence it, change the communication password, push network settings, and, behind typed confirmations, clear admins, fingerprints, users, transactions or everything. Every write is in the Command Log.
• Backups snapshot users, templates and settings nightly and on demand, kept seven days, and restore with an automatic safety backup first.
• Who: biometric.view (HR Manager, HR Officer) and biometric.manage (HR Manager); Super Admin everything.

Walkthrough

Northwind has one terminal registered, "Austin HQ — Main Entrance", a ZKTeco MB460 at an address that cannot be reached (it is a documentation address, deliberately), so Test connection and every sync fail with a connect timeout, no device users or raw punches exist, and the attendance rows that read Biometric were written by the demo generator rather than pulled. Everything below is written from the product; the sheet notes that a real device (C4) is needed to photograph it.

40.1 Adding a device with the detection wizard

Add Device opens the wizard on Connect: vendor (ZKTeco), IP or host, port (4370 by default), connection (TCP or UDP), the communication password if the device has one, and the timezone the device's clock is set to. Detect device probes the address and, when it answers, shows Connected with the model and platform, firmware, serial, device name, users on device and punch logs; a failure says Connection failed with the reason. Skip detection, add manually is for a device that is not reachable yet.

Details then takes the name (Main Entrance is the placeholder), the model (filled in when detected), an Area for grouping within a branch ("Main Entrance, Back Gate, Warehouse…"), the auto-sync interval in minutes, connect and command timeouts (15 and 30 seconds by default), and four switches: Active; Auto-sync enabled; Use device IN/OUT flag, off by default because most terminals never ask the person which way they are going, so Operentra treats the day's scans as odd and even, first IN, second OUT; and Clear device logs after successful sync, which the form marks irreversible and tells you to enable only once sync is proven stable. Notes close the form ("mounted at reception, runs on UPS backup").

Removing a device keeps the attendance history and the raw punches; auto-sync stops and the device vanishes from the list, and the same address can be registered again afterwards. Disabling it pauses auto-sync while leaving every manual operation available.

40.2 Device detail and storage

The device page shows what the terminal reported: firmware, fingerprint algorithm version, platform, serial, MAC, area and Device Time, which is the first thing to read when punches look wrong (40.12). Storage counts users, fingerprints, attendance logs, faces, palms, finger-veins and admins; the hint under the log count explains that a device counter can include historical allocations from clear-log events, and that every retrievable record is captured on sync. Sync shows auto-sync on or off, the interval, the IN/OUT mode (Device flag or Odd/Even order), clear after sync, last connected and last sync.

Buttons: Disable or Enable, Test Connection, Refresh Info (reads the device again), Fetch Users, Pull Fingerprints, Clean orphans when the device holds templates whose user record is gone, Fetch Latest and Fetch All; and links to Device Users, Punches, Sync History, Controls, Command Log, Push Employees and Backups.

40.3 Syncing: auto-sync, sync now, fetch latest, fetch all

A job runs every minute and, for each active device whose auto-sync interval has elapsed, reads the device's live log count; if it equals the count last pulled, nothing else happens, which keeps a quiet terminal from being read in full every ten minutes. When it differs, the buffer is pulled, new scans are stored as raw punches, merged into attendance, and the day's result is written to Sync History with the counts: fetched, new, unmapped, and the attendance rows touched.

Sync now on the device list does users and punches together. Fetch Latest on the device page is the same fast path by hand (the toast says "already up to date" when nothing changed); Fetch All forces a full buffer pull regardless of the gate, for re-verifying Operentra's data against the device. With clear-after- sync on, a successful pull that stored new punches ends by wiping the device's log, and the next count starts from zero.

The merge is the same on every path (the concept above): per device user per local day, first and last scan or the device's flag, graded with the shift and settings in force, approved overtime as the cap; days with a Regularized source, a Force lock, or a leave, holiday or weekend status are left exactly as they are, with the scans still recorded in the log for audit.

40.4 Device users: bind, unbind, edit, delete, identify a person

Device Users lists the terminal's people as it knows them: Device User ID, name on device, card number, role (User, Manager, Enroller, Admin), and the employee they are bound to. Three counters head the page, users on device, bound, unmapped, with an Unmapped filter and a search by ID, name or card. Nothing is here until Fetch Users has run.

Bind opens a dialog that suggests matches (an employee code equal to the device ID, or a name that contains the device name's words) and lets you search the whole employee list; binding reassigns every historical punch from that device user to the employee and promotes any fingerprint templates staged for them. Bulk bind does the same for many. Unbind marks the punches unmapped again without touching the device. Edit changes the name (24 characters), card, role and numeric password on the device, and manages the enrolled fingers (40.5). Delete wipes the user and their templates from the device and removes the mirror row; the punches stay in Operentra as the audit trail, and a re-push allocates a fresh ID.

Identify person answers "who is this device user" the honest way: Start takes a baseline, the person scans, Check finds the new punch and names the employee it belongs to, or says the device user is not bound and should be. Operentra stays off the device between the steps so the scan is not interrupted.

40.5 Fingerprint enrolment from Operentra; pulling fingerprints

Edit a device user and the Enrolled fingers section lists what Operentra tracks for them by finger (right thumb to left little). Enrolling a finger from here puts the terminal into enrolment mode for that user and finger ("Device is in enrollment mode — user should scan 3 times"); when the device accepts the scans, Operentra fetches the result and confirms with the before-and-after count. Cancelling takes the device out of the mode. A finger can be removed from the device while the captured template is kept, or deleted from both.

Pull Fingerprints on the device page copies every enrolled template into the per-employee library, upserting by employee and finger so it is safe to repeat; templates for unbound users are staged and promoted when the user is bound, and templates whose user no longer exists on the device are reported as orphans for Clean orphans to sweep. The library is what makes a fingerprint portable: the employee's Biometric card (Chapter 19) shows which devices they are on, which fingers the library holds, their past bindings, and offers Remove from all devices when they leave and Review and restore when they come back, pushing the stored templates to a compatible device so they can punch on day one.

40.6 Pushing employees to a device

Push Employees selects active employees (search by name, code or national ID; filter by department; select all visible) and creates a device user for each with the next free numeric ID, writing the employee's name to the device and storing the mapping so their punches resolve. The page explains the constraint: ZK firmware caps the on-device ID at nine digits and mangles anything else, so the ID is a number and the employee code is kept in the binding for reference. Pushing an already-mapped employee reuses their ID. The result table lists each employee with the device user ID or the failure. Fingerprints are still enrolled at the device (or from Operentra, 40.5) afterwards; a pushed user without a template cannot punch.

The onboarding checklist's "Enroll on biometric device" task runs this push for one new hire (Chapter 32).

40.7 The punches page and unmapped punches

Attendance › Biometric Punches is every raw scan from every device, filtered by device, date range and Unmapped only, with a CSV download: time, device, device user, employee, and the type. The page explains the type column: most terminals record every scan as Scan, and the merge decides IN and OUT by order (or by the flag when the device is set to use it); Check-out, Break-out, Break-in, OT-in and OT-out appear only from devices that record them.

An unmapped punch is a scan from a device user nobody has bound. It is kept, shown here, counted in Sync History, and turned into attendance the moment the user is bound, retroactively. A workspace with unmapped punches has attendance it cannot see yet, which is why the Device Users page counts them at the top.

40.8 Sync history and flushing stuck jobs

Sync History is the per-device log of every pull: started, duration, trigger (Auto-sync or Manual), users fetched and created, punches new over seen with the unmapped count, and a note. A job that died mid-run stays Running and blocks the next tick; Flush stuck marks those jobs failed with a "manually flushed" note so auto-sync resumes, without deleting the rows.

Northwind's history is a long column of failed jobs, one every ten minutes, because its address never answers; that is what a wrong address or a dead network looks like, and the fix is the address, the network, or disabling the device until it is back.

40.9 Device controls: time, date format, power, LCD, voice, network, danger zone

Controls gathers what otherwise needs the keypad, each action audited in the command log.

• Time: Sync time now pushes the server's time to the device, for DST changes and clock drift.
• Date format: the string the device shows on its LCD.
• Power state: Enable, Disable (to freeze the device during bulk work), Restart (offline for about thirty seconds), Power off (someone must switch it on again).
• LCD and voice: write a line to the screen, clear it, play the chime; Silent mode stops the chirp on every sync, and, because ZK firmware has one voice switch, also the punch confirmation beep.
• Comm password: changed on the device and re-encrypted in Operentra together.
• Network config: IP, subnet, gateway and device number, behind the device's serial typed as confirmation, because a wrong value makes the device unreachable until someone fixes it at the keypad.

The danger zone holds Clear Admin Privilege, Delete All Fingerprints, Delete All Employees, Delete All Transactions and Delete All Data, each with a typed confirmation and a warning that says what survives: Operentra's punch history, always.

40.10 Command log

Command Log is every write sent to the device: when, the command, the result, the duration, and the payload, for "who changed what on the terminal". Reads are not logged; a sync is in Sync History instead.

40.11 Device backups and restore

Backups are point-in-time snapshots of the device's users, fingerprint data and settings. A nightly job takes one for every active device (skipping a device mid-enrolment) and purges anything older than seven days; Backup now takes one on demand with an optional name ("Before firmware update"), kept under the same seven days. The table lists when, users, fingerprints, size and trigger.

Restore first takes an automatic safety backup of the device as it is, then probes whether this firmware accepts fingerprint writes by round-tripping the existing blob. If it does, the device is wiped and restored in full; if not, users are upserted and the on-device fingerprints are left alone, which the result banner reports as Users-only. The restore dialog warns when the backup has no recorded platform, when the device's platform is unknown (fetch device info first), and when the two differ, behind an "I understand the risk" switch, because a blob captured on different firmware can corrupt the device's fingerprint database. A typed word confirms. When the blob cannot be restored, Operentra falls back to the per-employee library, pushing templates one employee at a time, and says how many it managed.

40.12 Device-clock problems and what to do

A terminal's clock is a coin cell and a setting. When the cell dies, a power cut reboots the device into a default date far in the past or the future, and every scan until someone corrects it is stamped wrong. A future stamp is the dangerous one: a sync keeps only scans newer than the newest it has stored, so one scan from 2103 would make every real scan afterwards "already seen", and the device would report success with nothing new for weeks.

Operentra quarantines any punch stamped more than a day ahead as a device clock fault: it is stored, marked skipped, never used as the cutoff, never merged, and the sync result carries a warning. What to do: read Device Time on the device page, push Sync time now from Controls, and if the clock will not hold, replace the cell. The quarantined scans stay in the raw log; the real days they belong to are marked by HR (Chapter 38) and the device is the source again from the day the clock is right.

What happens next

• Attendance receives merged days with source Biometric; every rule in Chapters 34 to 36 applies to them.
• An employee who leaves is removed from the device from their Biometric card; one who rejoins is restored from the library.
• The capture card on Attendance Settings reads Set up and ready for the biometric method once an active device exists (Chapter 36).

What the employee sees

Nothing of this module. They scan at the door, hear the beep (unless silent mode), and see the day in their portal month with Biometric as its source.

Common mistakes

1. Trusting punches before binding. An unmapped scan is not attendance; bind the device user first and the history follows.
2. Enabling clear-after-sync on day one. It wipes the device's log after each pull; prove the sync first.
3. Switching the IN/OUT flag on without training. If staff do not choose IN or OUT on the device, the flag is noise; odd and even is the safer rule.
4. Pushing network settings without the serial to hand. The form refuses, and for good reason.
5. Restoring a backup across firmwares. The risk switch exists for the rare case you are sure; otherwise re-enrol.
6. Reading a Running job as progress. A job stuck for an hour is dead; flush it so the next tick runs.
7. Ignoring Device Time. The clock is the cause of most "the terminal shows success but nothing arrives" cases.
8. Deleting a device user to fix a wrong binding. Unbind instead; deletion wipes their fingerprints on the device.

Practice

Use your own trial workspace, not a customer's, and a test terminal if you have one.

1. Open Attendance › Biometric Devices and read the list's columns and action icons. Open Add Device, read the Connect step, and try Detect device on an address that cannot answer.
2. On a device page, read the Storage and Sync panels, then open Sync History and read one job's counts.
3. On Device Users, filter Unmapped, open Bind for one user, read the suggestions, and bind. Then Unbind and read the note.
4. Open Push Employees, select two people, push, and read the result table. Open the Command Log.
5. Open Backups, read the explainer under Restore, take a manual backup, and read the Controls page's danger zone without confirming anything.

Quiz

1. How does auto-sync avoid reading a quiet device in full every few minutes?

It reads the device's live log count first and pulls the buffer only when the count differs from the last pull. Fetch Latest does the same by hand; Fetch All bypasses the gate.

2. What does binding a device user to an employee do to past punches?

Reassigns every historical punch from that device user to the employee, so unmapped punches become attendance retroactively, and promotes any staged fingerprint templates to the employee's library.

3. Which days does the merge never overwrite?

Days with a Regularized source, a Force lock, or a leave, holiday or weekend status. Their scans are still recorded in the log.

4. What happens to a punch stamped a week in the future?

It is quarantined as a device clock fault: stored, marked skipped, never used as the sync cutoff and never merged, with a warning on the sync result.

5. What does Restore do before it touches the device?

Takes a safety backup of the device as it is, then probes whether the firmware accepts fingerprint writes; only then does it wipe and restore in full, or fall back to users only.