Biometric devices
How to register and manage time-attendance terminals in Heimdallone, map device users to employees, review punches, and resolve unmatched punches.
Biometric terminals (fingerprint / face / PIN clocks) send punches into Heimdallone, which turns them into attendance records. This page explains how to find the device screens, register a device, map device users to employees, and keep punches flowing cleanly.
Who manages devices
Device setup and punch review are for HR Admin, Payroll Admin, and Tenant Owner / Admin. Employees never see these screens — they just clock in.
Where to find it
Go to App → Attendance → Biometrics & Time Clocks. You'll see tabs:
- Overview — recent sync health and totals.
- Devices — the registry of terminals and import sources.
- Sync runs — a log of each sync batch (fetched / created / duplicate / unmapped / errors).
- Punch review — raw punches as they arrived.
- Unmatched punches / Exceptions — punches that couldn't be matched to an employee, for triage.
Register a device
Keep the key safe
The ingest key is a secret. It goes into the on-site agent's local configuration only — never share it, screenshot it into a ticket, or post it anywhere public. If it's lost, rotate it from the device screen to get a new one.
Field reference
- Name — how the terminal appears in lists and reports.
- Vendor / model — selects how punches are interpreted; the model line is cosmetic, the vendor (e.g. ZKTeco) chooses the adapter.
- Mode — how punches arrive (API ingest, CSV import, and others).
- Time zone — the zone the device clock is read in.
- Device ID — the identifier the on-site agent uses to send punches.
- Ingest key — the secret the agent authenticates with (shown once).
- Status — only an active device accepts punches; deactivate to stop ingest.
- Last sync — when punches last arrived successfully.
Map device users to employees
A terminal identifies each person by a device user ID (their enrolment slot on the device). Heimdallone matches punches to employees through that ID.
Why mapping matters
Unmatched punches are never guessed by name and never silently dropped — they wait in the queue until you map them, so nobody's hours are lost or attributed to the wrong person.
Check last sync and review punches
- Sync runs shows each batch and whether it succeeded; use it to confirm the terminal is still talking to Heimdallone.
- Punch review shows the raw punches; Overview summarises health.
- Resolved punches flow into Attendance records, which are then validated and (once approved) used by payroll.
What to check
- The device shows a recent Last sync and active status.
- The Unmatched punches queue is empty (or every entry is expected and pending a new hire's enrolment).
- New employees who clock in have a device-user mapping.
- Attendance records for clocked days are present and day-typed.
Troubleshooting
| Symptom | Likely cause / fix |
|---|---|
| No punches arriving | Device not active, or the on-site agent isn't running / can't reach Heimdallone. Check Sync runs. |
| Punches show as unmatched | The person's device user ID isn't mapped yet — map it in Unmatched punches. |
| Duplicate-looking punches | Safe — re-sent punches are de-duplicated automatically; the count appears under Sync runs. |
| Lost the ingest key | Rotate the key on the device screen and update the on-site agent. |
| Times look shifted by hours | Check the device time zone setting. |
On-site agent setup
Connecting the physical terminal involves an on-site agent and its local configuration. Its secrets (the ingest key) live in that agent's local configuration only — never in shared docs. Your administrator handles that setup as part of go-live; see the device setup admin note.