Biometric Attendance Sync Tool

TODO: Complete the documentation

Tested Devices

1. ZKTeco K40
2. ZKTeco TX628
3. ZKTeco nFace250

Install Pre-requisites

Python 3.6+

Linux

Install latest Python distribution:

$ sudo apt install python3-venv

Windows

Download and install latest Python distribution from official site:

https://www.python.org/downloads/windows/

Download and install Git SCM if using script (optional)

https://git-scm.com/download/win

Download the Script

Check and download latest release here:

https://github.com/frappe/biometric-attendance-sync-tool/releases

OPTIONAL: Download and install Microsoft C++ Build Tools

FIX: error: Microsoft Visual C++ 14.0 or greater is required. Get it with "Microsoft C++ Build Tools": https://visualstudio.microsoft.com/visual-cpp-build-tools/

https://visualstudio.microsoft.com/visual-cpp-build-tools/

Linux

Download latest source distribution:

$ wget https://github.com/frappe/biometric-attendance-sync-tool/archive/refs/tags/v1.0.tar.gz
$ tar -xvf v1.0.tar.gz

Windows

Download latest release:

# For 64-bit Windows
https://github.com/frappe/biometric-attendance-sync-tool/releases/download/v1.0/biometric-attendance-sync-tool-v1.0-win64.zip

# For 32-bit Windows
https://github.com/frappe/biometric-attendance-sync-tool/releases/download/v1.0/biometric-attendance-sync-tool-v1.0-win32.zip

Extract files to location:

C:\biometric-attendance-sync-tool-1.0

Download Source (Master)

$ cd ~
$ git clone https://github.com/frappe/biometric-attendance-sync-tool.git

Setup Specifications (For CLI)

Linux:

$ cd path/to/biometric-attendance-sync-tool
$ python3 -m venv venv
$ source venv/bin/activate
(venv) $ python3 -m pip install --upgrade pip   
(venv) $ pip install wheel
(venv) $ pip install -r requirements.txt

Windows:

> cd Drive:\patho\biometric-attendance-sync-tool
> python -m venv venv
> .\venv\Scripts\activate
(venv) > python -m pip install --upgrade pip    
(venv) > pip install wheel
(venv) > pip install -r requirements.txt

Linux

1. Setup dependencies

$ cd biometric-attendance-sync-tool-1.0
$ python3 -m venv venv
$ source venv/bin/activate
$ pip install wheel
$ pip install -r requirements.txt

2. Setup local_config.py

Make a copy of localconfig.py.template file and rename it to localconfig.py:

$ cp local_config.py.template local_config.py
$ gedit local_config.py


TODO

3. Run the script

$ python3 erpnext_sync.py

Windows

TODO: config env

> python -m pip install --upgrade pip
> pip install virtualenv
> cd path/to/bast
> python3 -m venv venv
> .\venv\Scripts\activate
> .\venv\Scripts\python.exe -m pip install --upgrade pip
> pip install -r requirements.txt

TODO: edit config file

Run script manually

> python erpnext_sync.py

Setup ERPNext site

Login to site

Login with user that has System Manager role:

https://erp.example.com/login

Custom Role and User for B.A.S.T

Create and Configure Custom Role:

Role -> Add Role
-> Role Name: Biomateric Attendance Sync Tool
-> Save

Role Permissions Manager:

Select Role -> Biomateric Attendance Sync Tool
Select Document Type -> Employee Checkin (Perm Level 0, 1)
-> Check Permissions: Create + Read + Write

Select Document Type -> Shift Type
-> Check Permissions: Read + Write

Create User:

User -> Add User
-> Email: bast.example@bcnerp.com
-> First Name: Biomateric Attendance Sync Tool
-> Send Welcome Email: False
-> Save

User -> Biomateric Attendance Sync Tool -> Edit
-> Roles - Check Role: Biomateric Attendance Sync Tool role
-> Save

Generate API Keys

User -> Biomateric Attendance Sync Tool -> Edit
-> API Access -> Click Generate Keys
-> Save API Secret: b72076bebbe5fdc

Save above api secret and key

API Key: 8c2c1cc0097aa41
API Secret: b72076bebbe5fdc

Configure Employee's Device ID

Employee -> Choose employee to setup Device ID
-> Attendance and Leave Details
    -> Attendance Device ID (Biometric/RF tag ID): 1 (integer value)

Configure Employee Checkin

Update B.A.S.T configs

Update ERPNext related configs:

ERPNEXT_API_KEY = 'xxxxxxxxxxxxxxx'
ERPNEXT_API_SECRET = 'xxxxxxxxxxxxxxx'
ERPNEXT_URL = 'http://erp.example.com'
ERPNEXT_VERSION = 14

IMPORT_START_DATE = "20240101"

Start Sync

$ python3 erpnext_sync.py

Running the script in production

Linux

Option 1: set as a Cron job

Edit crontab and add this line

$ crontab -e
...
60 * * * * cd /absolute/path/to/biometric-attendance-sync-tool && python3 -c "from erpnext_sync import main; main()" >> /absolute/path/to/biometric-attendance-sync-tool/logs/sync.log 2>&1

#TODO Call the main function using:

$ python -c "from erpnext_sync import main; main()"

Option 2: set as a service using Systemd

Refer to: https://tecadmin.net/setup-autorun-python-script-using-systemd/

Create Service File

Create a service file for the systemd with .service extension under /lib/systemd/system/ directory.

$ sudo nano /lib/systemd/system/erpnext-sync.service

Add the following content and save the service file.

[Unit]
Description=ERPNext Biometric Push Service
After=network.target

[Service]
Type=simple
WorkingDirectory=/home/USER/biometric-attendance-sync-tool
ExecStart=/home/USER/biometric-attendance-sync-tool/venv/bin/python3 erpnext_sync.py
User=USER
Group=USER
Restart=on-failure
StartLimitInterval=60

[Install]
WantedBy=multi-user.target

Refresh demon registry:

$ sudo systemctl daemon-reload

Stop the service (if it was running)

$ sudo systemctl stop erpnext-sync

Start the service:

$ sudo service dummy start

Windows

Installing as a Windows service:

1. Install pywin32 using pip install pywin32
2. Got to this repository's Directory
3. Install the windows service using python erpnextsyncwin.py install (erpnextsyncwin.py and SMWinservice.py are required in repo directory)
4. Done

Update the installed windows service:

> python erpnext_sync_win.py update

Stop the windows service:

>  net stop ERPNextBiometricPushService

To see the status of the service

mmc Services.msc