4.1 ZKTeco Device Setup
Before configuring the integration, verify the following on the physical device:
- The device is powered on and connected to the same network (or a routable network) as the Frappe server.
- The device's IP address is static or reserved via DHCP, so it does not change between syncs.
- The device's admin username and password are known.
- The REST API (ICLOCK interface) is enabled on the device. Most ZKTeco devices running firmware version 6.60 and above expose this by default.
- Ports are open: test reachability with
curl http://{device_ip}/iclock/api/transactions/from the Frappe server before proceeding.
4.2 ZKTeco Biometric Settings Doctype
Navigate to: ZKTeco Biometric Integration > ZKTeco Biometric Settings
ZKTeco Biometric Settings
Each settings document represents one ZKTeco device. You can create multiple settings documents to manage multiple devices.
| Field | Description | Example |
|---|---|---|
| Username | Admin username for the ZKTeco device. Must be unique per device. | admin |
| Password | Admin password for the ZKTeco device. | Admin1234 |
| URL | Base URL of the device, including scheme and IP. Do not include a trailing slash. | http://192.168.1.100 |
| Fetch Frequency | How often the scheduler pulls data from this device. See options below. | Hourly |
| Enable | Toggle to activate or pause this integration without deleting the settings. | Checked |
Fetch Frequency options:
| Option | Behaviour |
|---|---|
| All (Continuous) | Runs on every scheduler tick (approximately every minute). Use with caution on large deployments. |
| Hourly | Runs once per hour. |
| Daily | Runs once per day. |
| Weekly | Runs once per week. |
| Monthly | Runs once per month. |
| Custom Cron | Accepts a standard cron expression for precise scheduling (e.g., */15 * * * * for every 15 minutes). |
4.3 JWT Token Management
Saving the ZKTeco Biometric Settings document triggers automatic token generation. The system:
- POSTs the configured credentials to the device's auth endpoint.
- Stores the returned JWT token internally.
- Includes the token in the
Authorization: JWT <token>header on all subsequent requests. - Detects
401 Unauthorizedresponses and re-authenticates transparently before retrying.
You do not need to manually manage tokens. If authentication fails persistently, re-save the settings document to trigger a fresh token request, and verify credentials are correct.
4.4 Employee Biometric ID Mapping
Each employee in FrappeHR must have their Biometric ID set to the ID registered for them on the ZKTeco device.
- Open the Employee master record.
- Locate the Biometric ID field (under the Attendance section, or as a custom field depending on your HR configuration).
- Enter the exact numeric or alphanumeric ID that matches what the device records in the
emp_codefield of its punch transaction log.
Requirements:
- The Biometric ID must be unique across all employee records.
- It must match exactly no leading/trailing spaces, no formatting differences.
- If an employee is registered on multiple devices, the same Biometric ID must be used on all devices.
If an employee's Biometric ID is missing or does not match any punch record's emp_code, that employee's punches will be silently skipped. Check the Error Logs for Employee Not Found entries to identify mismatches.
4.5 Shift Assignment
The FrappeHR attendance processing pipeline (which converts raw Check-in records into Attendance documents) depends on employees having shifts assigned. Assign the appropriate Shift Type to each employee under the Employee master or via Shift Assignment before expecting attendance to be processed correctly from the synced data. The integration itself creates raw Employee Check-in records; shift resolution is handled downstream by FrappeHR's standard attendance automation.