Synchronization Process

The following describes what happens inside each sync cycle in detail.

Step 1: Scheduler fires

Frappe's background scheduler evaluates all active ZKTeco Biometric Settings documents. For each document where Enable is checked and the configured frequency interval has elapsed since last_sync_timestamp, the sync job is triggered.

Step 2: Authenticate

The system checks whether the stored JWT token is valid. If it has expired or is absent, re-authentication is performed using the stored credentials. A fresh token is stored before proceeding.

Step 3: Fetch transactions

The system calls the device's transaction endpoint:

GET {URL}/iclock/api/transactions/

The request includes filter parameters based on last_sync_timestamp to retrieve only new records since the last successful sync. The device returns a paginated JSON payload of punch records.

Step 4: Process each punch record

For each transaction record returned:

1. Read the emp_code field.
2. Query FrappeHR for an Employee whose Biometric ID matches emp_code.
3. If no match: log the error and skip.
4. If match found: check whether an Employee Check-in already exists for that employee at that exact timestamp. If a duplicate is found: skip.
5. If no duplicate: determine the log type. ZKTeco punch states are mapped as follows:

6. Create the Employee Checkin document with fields: employee, time (punch timestamp), log_type (IN/OUT), device_id (device URL for traceability).

Step 5: Update sync timestamp

After all records are processed, last_sync_timestamp is updated to the current time on the settings document. This prevents re-fetching already-processed records on the next cycle.

Step 6: Post-checkin device user control

After creating each Employee Check-in record, the integration calls the device's user management API to enable or disable the user on the device, based on the log type.