How to Connect and Manage Biometric Devices in CrmLeaf
All editions. Requires the Biometric add-on module to be enabled for your account by an Administrator, plus the manage_biometric_settings permission. In the Payroll & HR edition the feature is reached from a…
Availability: All editions. Requires the Biometric add-on module to be enabled for your account by an Administrator, plus the manage_biometric_settings permission. In the Payroll & HR edition the feature is reached from a dedicated Biometrics menu group. Core attendance already covers clock-in with geolocation and QR code; the Biometric module is what drives physical hardware.
Overview
The Biometric module connects physical fingerprint and card devices to CrmLeaf so that punches recorded at a device become attendance data in the platform. It is used where attendance must be captured at a fixed entry point rather than from a browser or a phone. Attendance captured this way feeds payroll in the same way as any other attendance record.
How It Works
CrmLeaf integrates devices using the ZKTeco ADMS "iclock" push protocol. The device pushes its data to CrmLeaf, and CrmLeaf can queue commands back to the device.
Enable module → Register device → Enrol employees → Device pushes punches → Attendance and payroll
- Devices shows the registered devices and their device status.
- Device Employees covers enrolled templates along with card and photo data.
- Attendance holds the device punches, each of which can carry a captured photo.
- Commands holds commands queued to a device, which the device collects when it communicates with CrmLeaf.
- Recent activity shows recent device communication, which is the first place to look when a device appears silent.
- A
force_biometric_clockinoption exists, so an organisation can require clock-in through the device.
Who Can Use This Feature?
Administrator
- Register and monitor biometric devices.
- Manage device employees, enrolled templates, card and photo data.
- Review device punches and recent device activity.
- Queue commands to a device.
- Enable the option that requires clock-in through a biometric device.
This functionality is available only to Administrators, and requires the manage_biometric_settings permission in addition to the Biometric module.
Prerequisites
- The Biometric add-on module enabled for your account.
- The
manage_biometric_settingspermission on your role. - A biometric device that supports the ZKTeco ADMS "iclock" push protocol.
- Employee records created in CrmLeaf before enrolment, so punches can be matched to employees.
- Attendance and shift configuration completed, since device punches are interpreted against the assigned shift.
- Network access from the device to CrmLeaf, arranged with your IT team.
For Administrators
Step 1: Confirm the module and permission
What to do: Confirm the Biometric module is enabled for the account, and that your role holds manage_biometric_settings.
What to verify: The Biometrics menu group is visible. Without both the module and the permission, the screens do not appear.
Step 2: Register the device
What to do: Add the device so CrmLeaf recognises it, then configure the device itself to push to CrmLeaf using the ZKTeco ADMS "iclock" protocol. Device-side configuration is done on the device or in its own utility, following the manufacturer's instructions.
What to verify: The device appears in Devices and its device status shows it is communicating.
Step 3: Enrol employees on the device
What to do: Match device users to CrmLeaf employee records and review the enrolled templates, card data and photo held for each.
What to verify: Every employee expected to clock in at the device is enrolled and linked to the correct employee record.
Step 4: Check punches are arriving
What to do: Have an enrolled employee punch at the device, then confirm the punch appears. Each punch can carry a photo captured at the device.
What to verify: The punch appears against the correct employee, with the expected date and time.
Step 5: Use device commands and recent activity
What to do: Queue a command to the device when you need it to act. Commands are collected by the device when it next communicates. Use Biometrics → Recent activity to see whether the device has been in contact.
What to verify: A queued command is collected, which confirms two-way communication rather than only inbound punches.
Step 6: Decide whether to require biometric clock-in
What to do: Where your policy requires attendance to be captured only at a device, enable the force_biometric_clockin option.
What to verify: Test the effect on employees who work away from the device before applying this to everyone.
Step 7: Confirm attendance flows into payroll
What to do: Before the first payroll run using device data, confirm the resulting attendance records for a sample of employees, then generate and review payroll for one department.
What to verify: Paid days on the payslips match the attendance derived from device punches.
Expected Result
The biometric device is registered and communicating, employees are enrolled, punches arrive in Attendance under the Biometrics group, and the resulting attendance is available to payroll.
Important Notes
- Menu names and their position can differ between product editions and can be customised for your account, so your sidebar may not match these paths exactly. Use Search or your Quick Access items if you cannot find a screen.
- Biometric is a paid add-on module. Confirm it is included in your plan, and note that the
manage_biometric_settingspermission is required in addition to the module. - Device support is documented for the ZKTeco ADMS "iclock" push protocol. Confirm compatibility before purchasing hardware.
- Biometric templates and captured photos are personal data. Confirm your legal basis for collecting them, your retention position and your employee notification obligations with a qualified advisor before deployment.
- Enabling
force_biometric_clockinaffects everyone it applies to. Consider employees who work remotely or in the field, since core attendance also supports geolocation and QR code clock-in. - Attendance affects pay. Confirm that device attendance is complete for a period before payroll is generated.
Common Scenarios
Example: a factory entry point. A manufacturer installs a device at the entrance, enrols shop-floor employees, and relies on device punches for their attendance, while office staff continue to clock in through core attendance.
Example: a device stops reporting. Payroll notices missing attendance. The Administrator checks Recent activity, finds no recent communication from the device, and works with the IT team on network access before payroll is generated.
Example: mixed workforce. An organisation enables the option to require biometric clock-in for site-based teams only, after testing it, so field employees are not blocked from recording attendance.
Troubleshooting
| Issue | Possible Cause | Resolution |
|---|---|---|
| The Biometrics menu group is not visible | The Biometric module is not enabled, or the role lacks manage_biometric_settings | Enable the module for the account and grant the permission to the role. |
| The device does not appear to be communicating | The device cannot reach CrmLeaf, or its push configuration is incomplete | Check Recent activity, then confirm the device's network access and push configuration with your IT team. |
| Punches arrive but are not linked to an employee | The device user is not matched to a CrmLeaf employee record | Link the device user to the employee in Device Employees. |
| A queued command is not carried out | The device has not yet communicated to collect it | Confirm the device is online in Recent activity, then check the command again. |
| Attendance from the device is missing on payslips | Punches for the period arrived after payroll was generated | Confirm attendance for the period is complete, then generate payroll again. |
Frequently Asked Questions
Which devices are supported?
Integration is documented for physical fingerprint and card devices using the ZKTeco ADMS "iclock" push protocol. Confirm a specific model with your Administrator before purchase.
Do I need the Biometric module for GPS or selfie attendance?
No. Core attendance handles clock-in with geolocation and work-from options, and the mobile app supports face and location verification. The Biometric module drives hardware devices.
Can I require employees to clock in only at a device?
Yes. A force_biometric_clockin option exists. Test its effect on remote and field employees first.
Are photos captured with punches?
A device punch can carry a captured photo, and enrolled device employee data can include a photo. Treat these as personal data.
Where do biometric punches end up?
In attendance, which is what payroll calculates paid days from.