Biometric Attendance Sync Tool

I’ve had this problem but chose to ignore since if you set the auto attendance settings as alternating entries as in and out, the first “IN” is “IN” but the second “IN” is defined as “OUT”. Can’t change this if your device’s default setting is inputting only “IN”. My auto attendance works fine too.

I got the solution! We need to setup our ZKTeco device (My device is ZKteco F18) for Log Type status issue.

Prerequisite:

  1. Create Shift Type and check the Enable Auto Attendance option.
  2. Assign Default Shift Type for all Employees.
  3. Assign Biometric/RF tag ID number (like 1, 2, 3 or 1001, 1002, 1003…) in application(Employee > Attendance and Leave Details > Attendance Device ID (Biometric/RF tag ID)) and also for the device as well for all employees.

ZKTeco device Setup Guide for Punch States Settings:

Step 1: In the initial interface, press [M/OK]. If you are an Administrator of this device, punch your ID Card or fingerprint to access the device menu.

Step 2: Go Personalize > Punch State Options from Menu

Step 3: First enable the Punch State Required by ON/OFF button (After enabling this button, you will see Log Type In/Out status in your ERPNext application). Then you need to choose an option from Punch State Mode according to your access control setup.

Step 4: Go Anti-passback Setup option from the Access Control menu. Then select Anti-passback Direction and Device Status options as per your need.

In my case, I am using ERPNext v14 in Oracle VM VirtualBox. I have a ZKTeco F18 device as a master unit for Check-In and ZKTeco FR1200 device as a slave unit for Check-Out. It is a Master-Slave configuration. According to my Access Control setup, I am using Normal Fixed Mode for Punch State Mode option. Then enabled the Anti-passback Setup option from the Access Control menu. Then chose the In for Device Status option and IN/OUT Anti-passback for the Anti-passback Direction option for strict access control configuration. Strict means, if you Check-In then you have to Check-Out when you exit or vice versa. No multiple/duplicate punch allowed here. If you don’t want the strict configuration then chose the Null and Save option. In this option Anti-passback function will be disabled but attendance state will be reserved and there will be no restriction for multiple/duplicate Check-In and Check-Out at a time.

After everything is done, You have to run the erpnext_sync.py by just pressing ENTER key after configuring the local_config.py file as per the Author’s Instruction. After that Everythihg should work!

Note: If we are using ERPNext v14, then we have to edit “frappe/biometric-attendance-sync-tool” - erpnext_sync.py file to work with ERPNext v14 otherwise Auto Attendance for Employee Checking will not work.

Edit line 180: Replace …/erpnext.hr.doctype… text with …/hrms.hr.doctype…

like this:

url = config.ERPNEXT_URL + "/api/method/erpnext.hr.doctype.employee_checkin.employee_checkin.add_log_based_on_employee_field"
to
url = config.ERPNEXT_URL + "/api/method/hrms.hr.doctype.employee_checkin.employee_checkin.add_log_based_on_employee_field"

Because, In ERPNext v14, HR module is a separate application(HRMS).

But there is still one problem which I am facing right now is Auto Attendance. Attendances not mark automatically. I have to press the Mark Attendance button for manual attendance everyday in Shift Type page. If anyone have any solution for this, please share it.

Reference manual link for ZKTeco F18 (Follow page no: 33 & 43): - ZKTeco F18 manual

3 Likes

Good catch. I’m sure this will be helpful to a bunch of people who are on V14 and find that the attendance is failing.

1 Like

@flexy2ky, @Ruhul_Kuddus

This issue has been fixed in feat: endpoint change for v14 by rtdany10 · Pull Request #35 · frappe/biometric-attendance-sync-tool · GitHub

Now this can be done by adding a key ERPNEXT_VERSION = 14 in your local_conf file.

Be sure to pull the latest code from the master branch.

2 Likes

Thanks for your quick response and solution. Really appreciated your effort.

1 Like

could you please recommend me a biometric device
preferably the brand and model number
i need to implement bio-metric attendance
Thanks in advance
Hemanth RK

getting below error in API call

2023-04-13 18:18:50,829 ERROR Error during ERPNext API Call. 669 1680321318.0 Traceback (most recent call last):
File “apps/frappe/frappe/app.py”, line 66, in application
response = frappe.api.handle()
File “apps/frappe/frappe/api.py”, line 54, in handle
return frappe.handler.handle()
File “apps/frappe/frappe/handler.py”, line 45, in handle
data = execute_cmd(cmd)
File “apps/frappe/frappe/handler.py”, line 83, in execute_cmd
return frappe.call(method, **frappe.form_dict)
File “apps/frappe/frappe/init.py”, line 1607, in call
return fn(*args, **newargs)
File “apps/hrms/hrms/hr/doctype/employee_checkin/employee_checkin.py”, line 107, in add_log_based_on_employee_field
doc.insert()
File “apps/frappe/frappe/model/document.py”, line 259, in insert
self.run_before_save_methods()
File “apps/frappe/frappe/model/document.py”, line 1045, in run_before_save_methods
self.run_method(“validate”)
File “apps/frappe/frappe/model/document.py”, line 914, in run_method
out = Document.hook(fn)(self, *args, **kwargs)
File “apps/frappe/frappe/model/document.py”, line 1264, in composer
return composed(self, method, *args, **kwargs)
File “apps/frappe/frappe/model/document.py”, line 1246, in runner
add_to_return_value(self, fn(self, *args, **kwargs))
File “apps/frappe/frappe/model/document.py”, line 911, in fn
return method_object(*args, **kwargs)
File “apps/hrms/hrms/hr/doctype/employee_checkin/employee_checkin.py”, line 24, in validate
self.fetch_shift()
File “apps/hrms/hrms/hr/doctype/employee_checkin/employee_checkin.py”, line 47, in fetch_shift
frappe.throw(
File “apps/frappe/frappe/init.py”, line 525, in throw
msgprint(
File “apps/frappe/frappe/init.py”, line 493, in msgprint
_raise_exception()
File “apps/frappe/frappe/init.py”, line 442, in _raise_exception
raise raise_exception(msg)
frappe.exceptions.ValidationError: Log Type is required for check-ins falling in the shift: Day.

2023-04-13 18:18:50,831 ERROR exception when calling pull_process_and_push_data function for device{“device_id”: “”, “ip”: “192.168.1.32”, “punch_direction”: “”, “clear_from_device_on_fetch”: “”}
Traceback (most recent call last):
File “C:\Users\nayang\Downloads\biometric-attendance-sync-tool-v1.0-win32\biometric-attendance-sync-tool-v1.0-win32\erpnext_sync.py”, line 51, in main
pull_process_and_push_data(device, device_attendance_logs)
File “C:\Users\nayang\Downloads\biometric-attendance-sync-tool-v1.0-win32\biometric-attendance-sync-tool-v1.0-win32\erpnext_sync.py”, line 129, in pull_process_and_push_data
raise Exception(‘API Call to ERPNext Failed.’)
Exception: API Call to ERPNext Failed.

Module
HR

Version
ERPNext: v14.20.3 (HEAD)

Frappe Framework: v14.31.0 (version-14)

Frappe HR: v14.2.1 (HEAD)

hello , i am using erpnext v14 on ubuntu 22.04

does those two lines will cause a problem since “pickledb” not supported on ubuntu 22.04 :

import pickledb
status = pickledb.load(‘/’.join([config.LOGS_DIRECTORY, ‘status.json’]), True)

Well I have the tool running on multiple instances with ubuntu 22.04 without issues.

@flexy2ky …thank you

i installed it but it gived this error

this is how local_config looks like :

# ERPNext related configs
ERPNEXT_API_KEY = '572a0470c2beae9'
ERPNEXT_API_SECRET = 'c39634366fd73da'
ERPNEXT_URL = 'http://192.168.1.50:8000'
#ERPNEXT_URL = 'http://dev.local:8000'
ERPNEXT_VERSION = 14


# operational configs
PULL_FREQUENCY = 1 or 60 # in minutes
LOGS_DIRECTORY = 'logs' # logs of this script is stored in this directory
IMPORT_START_DATE = '20230101' or None # format: '20190501'

# Biometric device configs (all keys mandatory)
    #- device_id - must be unique, strictly alphanumerical chars only. no space allowed.
    #- ip - device IP Address
    #- punch_direction - 'IN'/'OUT'/'AUTO'/None
    #- clear_from_device_on_fetch: if set to true then attendance is deleted after fetch is successful.
                                    #(Caution: this feature can lead to data loss if used carelessly.)

devices = [{"device_id": "CQDT231760076", "ip": "192.168.1.51", "punch_direction": None, "clear_from_device_on_fetch": False}]

# Configs updating sync timestamp in the Shift Type DocType 
# please, read this thread to know why this is necessary https://discuss.erpnext.com/t/v-12-hr-auto-attendance-purpose-of-last-sync-of-checkin-in-shift-type/52997
#shift_type_device_mapping = [
#    {'shift_type_name': ['Shift1'], 'related_device_id': ['test_1','test_2']}
#]

shift_type_device_mapping = [{'shift_type_name': 'shift2', 'related_device_id': 'CQDT231760076'},]

# Ignore following exceptions thrown by ERPNext and continue importing punch logs.
# Note: All other exceptions will halt the punch log import to erpnext.
#       1. No Employee found for the given employee User ID in the Biometric device.
#       2. Employee is inactive for the given employee User ID in the Biometric device.
#       3. Duplicate Employee Checkin found. (This exception can happen if you have cleared the logs/status.json of this script)
# Use the corresponding number to ignore the above exceptions. (Default: Ignores all the listed exceptions)
allowed_exceptions = [1,2,3]

@hayyan_daood First rule of thumb: Never display valid api key and secret in public post. you are opening up yourself to possible external intrusion. That being said, you should share the data from the logs folder. The logs in there would help to better understand the issue you’re facing if your config is correct.

@flexy2ky

i use this credentials on internal network not online . thx for caring ,

this is from log file :

“POST /api/method/hrms.hr.doctype.employee_checkin.employee_checkin.add_log_based_on_employee_field HTTP/1.1” 403 -

No this is the bench console. I mean the log file in the tool’s directory. go to biometric_sync_tool → logs → logs.log or error.log. open any of the files and show the data.

@flexy2ky

logs.log file

2023-08-25 16:16:49,743 INFO Mission Accomplished!
2023-08-25 16:17:49,795 INFO Cleared for lift off!
2023-08-25 16:17:49,795 INFO Processing Device: CQDT231760076
2023-08-25 16:17:49,795 ERROR Device Attendance Dump Found in Log Directory. This can mean the program crashed unexpectedly. Retrying with dumped data.
2023-08-25 16:17:49,820 INFO Mission Accomplished!

error.log

2023-08-25 16:18:49,940 ERROR exception when calling pull_process_and_push_data function for device{“device_id”: “CQDT231760076”, “ip”: “192.168.1.51”, “punch_direction”: null, “clear_from_device_on_fetch”: false}
Traceback (most recent call last):
File “/home/hayyan/biometric-attendance-sync-tool-master/erpnext_sync.py”, line 62, in main
pull_process_and_push_data(device, device_attendance_logs)
File “/home/hayyan/biometric-attendance-sync-tool-master/erpnext_sync.py”, line 140, in pull_process_and_push_data
raise Exception(‘API Call to ERPNext Failed.’)
Exception: API Call to ERPNext Failed.

@flexy2ky

and this is from the attendance failed log

2023-08-25 13:28:32,932 ERROR 403 2 1 1692069183.0 255 1 {“uid”: 2, “user_id”: “1”, “timestamp”: “2023-08-15 03:13:03”, “status”: 1, “punch”: 255}

@Nayan_Gajjar

hello , i have the same problem , did you find a solution for this problem ??

change api call url to this in erpnextsync.py: /api/method/hrms.hr.doctype.employee_checkin.employee_checkin.add_log_based_on_employee_field

it would be great if you could share the code that you used besides that already on the github.

am inquiring when you run the gui do the logs get imported to erpnext? because am kinda in the same situation

We recently install 7 biometric machines and all machines attendance data is synced into Employee Check in Screen in ERPNext 14 using biometric sync tool.
ERPNext is installed on cloud while three machines are installed in our head office, two machines are installed on one site and two machines are installed on another site.
Above mentioned two sites are connected with head office LAN and head office LAN is connected with cloud thru site to site VPN.
We have 87 shifts defined and assigned to employees (So many shifts are defined to avoid request timeout error) .
Auto attendance is enabled in every shift.

Now come to problem. If we stop syncing biometric machine and start syncing again after a gap of two or more days, the time column in employee check in screen shows date time of syncing date and time which is wrong. It should show checked in and checked out date time saved in biometric machine instead of date time when synced.
Even if we do not stop syncing biometric machines, there is a difference in time of check in/out of almost 20 to 45 minutes (which we think due to defined sync frequency of 15 minutes plus syncing time taken by remaining six machines).
Next problem is, Attendance is not marked automatically as present or absent after check in/out records are fetched from biometric machines to employee check in screen in ERPNext.

To diagnose the problem, We exported the vm from cloud and imported in ESXi 6.5 server placed locally in our head office. When we synced it with biometric machines after generating it’s new secret key it started fetching correct date and time in time column of Employee Checkin screen. Here correct means date and time saved in biometric machine (punch check in check out date time saved in biometric machine) .

What could be the issue in cloud? We checked date time and timezone of cloud VM which is correct. Cloud VM is Sangfor based while local server vm is ESXi 6.5 based.

Kindly guide how to diagnose this issue which is appearing in cloud VM and not appearing in local server while the code is same in both VMs except secret key of biometric attendance sync tool API which was generated again in local server.

How can we resolve these two issues:

  1. Actual date and time of check in/out to be fetched in time column of employee check in screen instead of syncing date time fetched in time column of employee check in screen.
  2. Auto attendance should work and mark absent or present when attendance data is fetched in employee check in screen.