Work Locations, Geofencing & Biometric Devices

Access

Work Locations and Biometric Devices are part of the Time & Attendance module. Configuration requires manage_attendance_config, separately from timesheet management. Clock/attendance users have narrower access to active locations and the geofence setting needed by the clock flow.

Work locations

Set up a workplace

1. Open Work Locations and create the site employees will clock in from.
2. Enter its coordinates and radius. Use the actual clocking area, rather than an unrelated postal-address point, when choosing the centre.
3. Choose whether it applies company-wide or to particular teams. Check that the intended employees belong to those teams.
4. Review the location's enforcement setting and the company enforcement toggle described below before asking staff to use it.
5. Try a clock-in from the intended area and review the recorded location and date. A location configured on a map is not evidence that a particular phone can obtain a fix there.

Create a location with a name, coordinates and radius; address and team scope are optional. A company-wide location applies to employees across teams. Team locations apply through the employee's team membership or direct team assignment. Only active locations are considered.

The company Geofence Enforcement toggle and the location's Enforce geofence setting work together:

• Company enforcement off: locations can still supply a coordinate/timezone match, but do not restrict clock-in.
• No active enforced locations anywhere in the company: there is nothing to enforce yet.
• Enforcement on, with enforced locations configured, but none applicable to the employee: clock-in is rejected.
• Applicable locations exist but are informational only: the employee's clock-in is unrestricted.
• Applicable enforced locations exist: valid coordinates must fall within at least one enforced radius for clock-in.

Distances use the haversine calculation. Coordinates are checked for valid ranges and missing values. A matching work location can determine the entry's calendar timezone, with company timezone fallback.

Clock-out differs from clock-in

The backend lets an existing open entry close even if location is missing or outside the fence. It records a [Geofence] note for review instead of leaving the entry open. A geofence exception prevents automatic approval.

The mobile screen can still stop submission when it has loaded an enabled geofence setting and cannot obtain usable coordinates. It discards device-reported mocked fixes and requests a cached fix no older than 60 seconds with accuracy within 250 metres when live attempts fail. These checks do not establish that every spoofed location will be detected.

See Time Entries for corrections and approval.

Registering biometric devices

The page has Devices, Enrollments and Logs tabs. Register a name, company-unique serial number and device type. The current types are ZKTeco, Hikvision and Generic REST. Optional device details include model, location, work-location association and IP address. A work-location association supplies timezone context for punches.

Device keys are shown once on creation or regeneration. Only a hash is stored, and normal device reads do not return it. Regenerating changes the key accepted by key-authenticated ingress.

Ingestion paths

Device integration	Endpoint and authentication
Generic REST	POST /api/biometric/webhook/push using X-Api-Key
Hikvision events	POST /api/biometric/webhook/hikvision/:deviceKey; the device key is part of the URL
ZKTeco ADMS	Root /iclock/getrequest, /iclock/cdata, /iclock/devicecmd and /iclock/ping routes; serial-based registration with explicit ADMS opt-in

ADMS serial numbers are identifiers, not secrets. Authentication also checks the registered source IP when supplied and rejects ambiguous serials across companies. The device must be active and its company licensed. Do not assume ADMS has the same authentication strength as a per-device secret. Configure the reader using the relevant device instructions in the page and confirm real punches in Logs.

Native Hikvision processing accepts supported event JSON, including its multipart event field, and does not retain accompanying face images. Native protocols feed the same attendance integration as the generic webhook. Code support is not certification of every hardware model or firmware version.

Enrollment mappings

Connect a reader to employee records

1. Register the reader in Devices, selecting the correct integration type and work location.
2. Copy the key when shown and follow that integration's configuration instructions. Treat a key-bearing URL like a credential.
3. Open Enrollments and map the reader's badge/enrollment identifier to the correct employee.
4. Submit a test punch from the reader and check Logs, then check the employee's time entry.
5. Test clock-out as well as clock-in before relying on the reader for attendance.

Arche's employee mapping is separate from enrolling a person on the physical reader. Use the reader's own enrollment procedure to obtain the identifier you map here.

Map the badge/enrollment ID to an employee. Mappings can be device-specific or company-wide. Resolution prefers the device mapping, then the company-wide fallback. This allows identical badge numbers on different readers to identify different employees without a company-wide collision.

A missing mapping is a processing problem to resolve in Enrollments. Reprocess eligible failed log rows after correcting the mapping.

Punch processing and review

The integration logs accepted punches and applies timestamp, replay and duplicate-punch checks before creating or updating attendance. Direction can be in, out or unknown; unknown punches use the current entry state. Overnight and split-shift matching are supported, and questionable sessions can require correction instead of receiving guessed working hours.

Use Logs to inspect processing status and errors. Not every raw network request becomes a punch log: authentication failures and vendor records that cannot be translated are rejected or skipped earlier. Check the configured reader, event shape, device status, work-location timezone and enrollment mapping when a punch is absent.

Employees can submit their account of missing or incorrect time through the correction workflow. A manager reviews it before attendance changes; see Time Entries.

Troubleshooting

Symptom	What to check
Clock-in says no location is available	Phone location permission and service, then the employee's applicable enforced locations
An employee at the site is outside the radius	Site coordinates/radius and the phone's reported position
A reader punch has no employee	Badge identifier and device-specific/company-wide enrollment mapping
A punch appears on the wrong calendar date	Reader timestamp and associated work-location timezone
Nothing appears in Logs	Reader endpoint, authentication, active device state and supported event format
A log has failed after a mapping error	Correct the mapping, then reprocess the eligible failed log

Do not invent an employee's working hours to make a failed punch disappear. Use the correction workflow to record the actual span and reason when attendance needs review.