Integrating Frappe HR with Biometric Attendance Devices
The punch logs from a biometric device are simply an employee’s check-in and check-out records. Frappe HR stores these in the Employee Checkin document, and then Auto Attendance marks attendance from those logs based on each employee’s Shift Type. So integrating a biometric device (or any access-control system that produces IN/OUT logs) comes down to two things: setting up Auto Attendance, and getting your device’s punch logs into Employee Checkin.
Step 1: Set up Auto Attendance
Before importing or syncing any logs, set up your employees and their shifts so attendance can be generated automatically. This means defining a Shift Type with Auto Attendance enabled, assigning shifts to employees, and mapping each employee’s Attendance Device ID. Once that’s in place, you’re ready to bring in the logs.
Step 2: Get the punch logs into Employee Checkin
Depending on your device and how automated you want it, there are three common methods.
Method 1 – Data Import Tool (simplest)
Export an Excel/CSV of the check-in/check-out logs and use Frappe HR’s built-in Data Import tool to import them into Employee Checkin periodically. It’s the easiest to implement, but you do it manually on a schedule.
Method 2 – API integration (automated)
Automate syncing by pushing logs to Frappe HR’s API. This needs some technical knowledge, your implementor or device vendor can usually help. The steps:
- Create a dedicated user in Frappe HR with permission to create Employee Checkin records (the API requires login).
- Generate an API Key and API Secret for that user for authentication.
- Set the Attendance Device ID (Biometric/RF tag ID) on each employee to match your device’s IDs.
- Send a POST request for each punch to: /api/method/hrms.hr.doctype.employee_checkin.employee_checkin.add_log_based_on_employee_field
The endpoint finds the right employee from the device ID and creates an Employee Checkin. Its main parameters:
- employee_field_value – the Attendance Device ID from your logs (and set on the employee).
- timestamp – the log time, as a string like ‘2022-04-08 10:48:08.000000’.
- device_id (optional) – a short location/device identifier.
- log_type (optional) – direction of the punch (IN/OUT), if known.
- skip_auto_attendance (optional) – set this log to be skipped by Auto Attendance (0/1).
- employee_fieldname (default: attendance_device_id) – the Employee field used for the lookup.
- latitude / longitude (optional) – used when a shift location is assigned.
The response is the created Employee Checkin record.
Method 3 – Python sync script for ZKTeco-type devices
For ZKTeco or similar devices that use the ZKProtocol over TCP/IP, Frappe provides a ready-made biometric-attendance-sync-tool. You run it on a computer; it pulls logs from the device and pushes them into Frappe HR using the API from Method 2. Follow the instructions on the tool’s page to set it up.
TIP
Match the method to your setup: Method 1 if you’re happy importing logs manually, Method 3 for a single location where the sync tool can sit on the same network as the device, and Method 2 (vendor API sync) for multi-location setups.
Frequently Asked Questions
How do I pick a biometric device that’s compatible with Frappe HR?
If you use Method 1 or Method 2, compatibility isn’t a concern, you’re just importing or posting data. For Method 3, the sync tool works with devices supported by the pyzk library typically any ZKTeco or similar device communicating via ZKProtocol over TCP/IP. Because compatibility depends on several factors, it’s worth asking the vendor for a device trial so you can test it with the sync tool before buying.
Which integration method should I use?
Method 1 works in any situation but needs you to import logs periodically by hand. Methods 2 and 3 are a one-time setup that then runs automatically (with some monitoring).
- Single location: the push sync tool (Method 3) communicates with the device over TCP/IP, so it usually needs to run on the same LAN as the device, then syncs to Frappe HR via API. This suits a single site well.
- Multiple locations: Method 2 is usually recommended — many biometric vendors offer services to sync logs from several locations into Frappe HR via the API. Method 3 can also work here if you have the networking know-how.
Related Topics
- Auto Attendance
- Employee Checkin
- Shift Type
SUMMARY
Integrating a biometric device means storing its punch logs as Employee Checkin records and letting Auto Attendance mark attendance from them. First set up Auto Attendance (shifts and Attendance Device IDs), then bring in the logs by one of three methods: the Data Import tool (manual, simplest), the API endpoint add_log_based_on_employee_field (automated, needs an API user and device-ID mapping), or the biometric-attendance-sync-tool for ZKTeco-type devices. Methods 1 and 2 avoid compatibility concerns; for the sync tool, use a pyzk-compatible ZKProtocol device. Choose Method 3 for single-location and Method 2 for multi-location setups.
