Installation

Step 1: Install Python Dependency

Install the required ZKTeco library on your Odoo server:

                                                    
pip install pyzk
                                                
                                                

Step 2: Install the Module

1. Copy the module into your custom addons directory.
2. Update the Apps List.
3. Search for:

                                                    
ZKTeco Biometric Attendance
                                                
                                                

1. Click Install.

Step 3: Verify Dependencies

Ensure the following Odoo modules are installed:

• Employees
• Attendances

Device Setup

Step 1: Create a Device

Navigate to:

                                                    
Attendance → Configuration → Devices
                                                
                                                

Create a new device and configure:

Field	Description
Device Name	Friendly device name
IP Address	Device IP
Port	Usually 4370
Password	Device password (if configured)
Protocol	TCP or UDP
Timeout	Connection timeout
Attendance Mode	Check-In, Check-Out, or Both

Step 2: Test Connection

Click:

                                                    
Test Connection
                                                
                                                

The module will verify:

• Device availability
• Network connectivity
• Authentication
• Communication settings

If successful, device status changes to:

                                                    
Connected
                                                
                                                

Step 3: Enable Automatic Sync

Keep the device active so attendance can be fetched automatically by scheduled jobs.

Employee Mapping

Employee mapping links biometric user IDs with Odoo employees.

Without mapping, attendance records cannot be assigned to employees.

Step 1: Open Employee Mapping

Navigate to:

                                                    
Attendance → Configuration → Employee Mapping
                                                
                                                

Step 2: Create Mapping

Create a mapping record:

Field	Example
Device	Main Office Device
Employee	John Doe
Device User ID	101

Step 3: Repeat for All Employees

Each biometric user ID should be linked to exactly one employee.

Unmapped Employees

If a biometric user ID is not mapped:

• Attendance is skipped
• Queue log is created
• Failure reason is recorded

Example:

                                                    
Employee mapping not found
                                                
                                                

Queue Processing

The module uses a queue-based architecture to ensure safe attendance processing.

Attendance Fetch Process

When attendance is fetched:

                                                    
Device
                                                        
                                                        
                                                        
                                                        
                                                        
   ↓
                                                        
                                                        
                                                        
                                                        
                                                        
Attendance Records
                                                        
                                                        
                                                        
                                                        
                                                        
   ↓
                                                        
                                                        
                                                        
                                                        
                                                        
Queue Creation
                                                        
                                                        
                                                        
                                                        
                                                        
   ↓
                                                        
                                                        
                                                        
                                                        
                                                        
Queue Lines
                                                    
                                                
                                                    
                                                    
                                                    
                                                    
                                                

Each fetch operation creates:

• One Queue
• Multiple Queue Lines
• Attendance Records

Queue Line Status

Success

Attendance record successfully imported.

Failed

Attendance could not be imported.

Examples:

                                                    
Employee mapping not found
                                                        
                                                        
                                                        
                                                        
                                                        
Duplicate attendance
                                                  
                                                
                                                    
                                                    
                                                    
                                                    
                                                

Queue Status Flow

                                                    
Draft
                                                        
                                                        
                                                        
                                                        
                                                        
   ↓
                                                        
                                                        
                                                        
                                                        
                                                        
In Progress
                                                        
                                                        
                                                        
                                                        
                                                        
   ↓
                                                        
                                                        
                                                        
                                                        
                                                        
Done / Failed
                                                    
                                                
                                                    
                                                    
                                                    
                                                    
                                                

A queue is marked as Done when all successful queue lines have been processed.

Punch Conversion

ZKTeco devices store punches individually.

Example:

Time	Punch
08:00	Check In
12:00	Check Out
13:00	Check In
17:00	Check Out

The module converts these punches into Odoo attendance sessions.

Result:

Check In	Check Out
08:00	12:00
13:00	17:00

Processing Logic

Records are grouped by employee and sorted by attendance date.

Check-In

The system stores the check-in punch temporarily.

Check-Out

The next checkout punch is paired with the previous check-in punch.

The resulting attendance is created in:

                                                    
HR Attendance
                                                
                                                

Example

Biometric Punches:

                                                    
08:00 Check In
                                                        
                                                        
                                                        
                                                        
                                                        
12:00 Check Out
                                                        
                                                        
                                                        
                                                        
                                                        
13:00 Check In
                                                        
                                                        
                                                        
                                                        
                                                        
17:00 Check Out
                                                    
                                                
                                                    
                                                    
                                                    
                                                    
                                                

Generated Odoo Records:

                                                    
08:00 → 12:00
                                                        
                                                        
                                                        
                                                        
                                                        
13:00 → 17:00
                                                    
                                                
                                                    
                                                    
                                                    
                                                    
                                                

Cron Configuration

The module includes automated scheduled jobs.

Attendance Fetch Cron

Responsible for downloading attendance from connected devices.

Process:

                                                    
Device
                                                        
                                                        
                                                        
                                                        
                                                        
   ↓
                                                        
                                                        
                                                        
                                                        
                                                        
Fetch Attendance
                                                        
                                                        
                                                        
                                                        
                                                        
   ↓
                                                        
                                                        
                                                        
                                                        
                                                        
Create Queue
                                                        
                                                        
                                                        
                                                        
                                                        
   ↓
                                                        
                                                        
                                                        
                                                        
                                                        
Create Queue Lines
                                                    
                                                
                                                    
                                                    
                                                    
                                                    
                                                

Recommended Frequency:

                                                    
Every 5 Minutes
                                                
                                                

Queue Processing Cron

Responsible for processing queued attendance records.

Process:

                                                    
Queue
                                                        
                                                        
                                                        
                                                        
                                                        
   ↓
                                                        
                                                        
                                                        
                                                        
                                                        
Attendance Processing
                                                        
                                                        
                                                        
                                                        
                                                        
   ↓
                                                        
                                                        
                                                        
                                                        
                                                        
Create HR Attendance
                                                    
                                                
                                                    
                                                    
                                                    
                                                    
                                                

Recommended Frequency:

                                                    
Every 1 Minute
                                                
                                                

Managing Scheduled Actions

Navigate to:

                                                    
Settings → Technical → Scheduled Actions
                                                
                                                

You can:

• Enable or disable jobs
• Change execution intervals
• Monitor execution history
• Review processing logs

Best Practice

For optimal performance:

• Fetch Attendance Cron → Every 5 Minutes
• Queue Processing Cron → Every 1 Minute

This ensures attendance is synchronized continuously without overloading the server or biometric devices.

Frequently Asked Questions

Which ZKTeco devices are supported?

This module supports ZKTeco biometric devices that are compatible with the Python pyzk library and communicate through TCP/IP or UDP.

Does this module support multiple devices?

Yes.

You can configure multiple biometric devices and synchronize attendance from each device independently.

Can I use both TCP and UDP connections?

Yes.

The device configuration allows you to choose:

• TCP

• UDP

depending on your network setup and device requirements.

How are employees identified?

Employees are identified through the Employee Mapping configuration.

Each biometric User ID must be mapped to an Odoo employee before attendance can be processed.

What happens if an employee mapping is missing?

The attendance record is not processed.

A queue log entry is created with the reason:

                                                    Employee mapping not found

                                                

This helps administrators identify unmapped users quickly.

Does the module create HR Attendance records directly?

No.

Attendance is first imported into an intermediate attendance table and then processed through a queue mechanism before creating Odoo HR Attendance records.

This provides better reliability and auditing.

Why does the module use queues?

Queues help:

• Prevent data loss

• Handle large attendance volumes

• Track processing status

• Log failures and conflicts

• Improve system stability

How are duplicate attendance records handled?

The module checks for existing attendance records before creating new ones.

If a duplicate is detected, it is skipped and logged accordingly.

How does punch conversion work?

ZKTeco devices generate separate punches:

Check In
Check Out

The module automatically pairs these punches and converts them into standard Odoo attendance sessions.

Example:

08:00 Check In
17:00 Check Out

becomes:

Check In : 08:00
Check Out : 17:00

inside Odoo HR Attendance.

Can attendance be synchronized automatically?

Yes.

The module includes scheduled actions (Cron Jobs) for:

• Fetching attendance from devices

• Processing attendance queues

No manual intervention is required after setup.

Can attendance be fetched manually?

Yes.

Administrators can fetch attendance directly from the device screen using the Fetch Attendance action.

What happens if the device is offline?

The fetch process will fail gracefully and log the error.

Examples:

Device unreachable
Connection timeout
Authentication failure

Can I review processing history?

Yes.

Every synchronization creates:

• Queue

• Queue Lines

• Attendance Records

allowing complete traceability of imported attendance data.

What do the queue statuses mean?

Status	Description
Draft	Waiting for processing
In Progress	Currently processing
Done	Processing completed
Failed	Processing failed
Cancelled	Queue cancelled manually

What do the attendance statuses mean?

Status	Description
Draft	Waiting for processing
Validated	Successfully processed
Conflict	Processing failed or attendance conflict detected

Is timezone supported?

Yes.

The module supports timezone-aware attendance processing and works correctly with Odoo's timezone management system.

Is the module suitable for large organizations?

Yes.

The queue-based architecture is designed to handle large attendance volumes across multiple devices and employees efficiently.

Which Odoo applications are required?

The following standard Odoo applications are required:

• Employees

• Attendances

Is technical knowledge required to use the module?

No.

After device setup and employee mapping, attendance synchronization can run automatically using scheduled actions.