Skip to Content

ZKTeco Attendance

by
Odoo

$ 109.52

v 18.0 Third Party
You bought this module and need support? Click here!
Availability
Odoo Online
Odoo.sh
On Premise
Odoo Apps Dependencies • Attendances (hr_attendance)
• Employees (hr)
• Discuss (mail)
Lines of code 891
Technical Name de_zkteco_attend
LicenseOPL-1
Websitehttps://dynexcel.com

Biometric Device Integration for Odoo HR

ZKTeco Devices,

Odoo Attendance,

One System

Connect your ZKTeco biometric machines to Odoo HR Attendance with a robust queue-based processing pipeline. Automatic fetching, duplicate prevention, punch conversion, and full audit trails — out of the box.

Explore Features Get Support

5+
Data Models
2
Scheduled Crons
18 / 19
Odoo Versions

ZKTeco Device - Live
Main Gate Device
192.168.1.101 : 4370 / TCP
ONLINE
Protocol
TCP
Port
4370
Connection
OK
Last Sync
09:01 AM
Timeout
5s
Mode
Auto
Latest Punches
John Doe 08:02 Check In
Jane Smith 08:05 Check In
John Doe 12:00 Check Out
Queue Processing Pipeline
D
Device
>
P
Punches
>
Q
Queue
>
A
Attendance
What is this module?

Queue-Based Biometric Attendance for Odoo

This module bridges ZKTeco biometric hardware and Odoo's hr.attendance model with a reliable, asynchronous processing pipeline. Raw punches are fetched, validated, queued, and converted into clean Odoo attendance records — automatically, on a schedule.

📱 Multi-Device Support

Connect any number of ZKTeco devices — TCP or UDP — each with its own IP, port, password, and timeout configuration. Test connectivity with one click.

⏳ Asynchronous Queue

Punches are never processed synchronously. They enter an intermediate queue first, ensuring no data is lost even if processing fails partway through.

🔄 Smart Punch Conversion

Separate Check-In / Check-Out punches from the device are automatically paired into complete Odoo attendance records — 4 punches become 2 clean attendance entries.

Key Capabilities

Everything Built In

Multiple Device Support

Manage any number of ZKTeco biometric devices from a single Odoo interface — each independently configured and monitored.

TCP & UDP Protocols

Supports both TCP and UDP connection modes, covering the full range of ZKTeco device network configurations in the field.

Device Connection Testing

Test connectivity directly from the device form with the built-in Test Connection button — no separate tools needed.

Automatic Fetch via Cron

A scheduled cron automatically downloads punches from all connected devices on a configurable interval — fully hands-free.

Employee-Device Mapping

Map biometric User IDs to Odoo employees individually, supporting multi-device environments where one employee uses multiple machines.

Queue-Based Processing

All fetched punches pass through an intermediate queue before becoming attendance records — providing reliability and safe retry capability.

Queue Logs & Tracking

Every queue line records its processing outcome — success or failure — with a message explaining exactly what happened.

Duplicate Prevention

Built-in duplicate detection prevents the same punch from creating multiple attendance records, even if a device re-sends data.

Conflict Handling

Invalid sequences and Odoo validation errors are caught and flagged as Conflict state with a reason — never silently dropped.

Setup Workflow and Architecture

Three Steps to Go Live

From hardware to Odoo attendance records — a clear, predictable pipeline every step of the way.


01
Configure Device
Create a device record at Attendance > Configuration > Devices . Enter the IP Address, Port, Password and Protocol. Use Test Connection before saving.
02
Map Employees
Link each ZKTeco User ID with the corresponding employee from Attendance > Configuration > Employee Device Mapping .
03
Fetch and Process
Attendance Fetch Cron downloads punches automatically. Queue Processing Cron converts them into hr.attendance records automatically.

ZKTECHO Device

Fetch attendance (Cron 1)

Draft Attendance

Queue

Queue Attendance (Cron 2)

Odoo Attendance

Watch It in Action

Full Module Demo

See the complete flow — from adding a ZKTeco device, mapping employees, triggering a fetch, and watching attendance records appear in Odoo HR.

Documentation and Guidance

Everything You Need to Get Started

From installing the Python dependency to configuring scheduled crons — complete guides for every step.

Overview

The ZKTeco Biometric Attendance module connects ZKTeco biometric devices with Odoo and automates the attendance management process.

Attendance punches are fetched directly from biometric devices, stored in an intermediate attendance table, and then processed into Odoo's standard HR Attendance records through a queue-based system.

This approach ensures:

  • Reliable attendance synchronization
  • Prevention of duplicate records
  • Employee mapping validation
  • Attendance conflict handling
  • Background processing through scheduled actions
  • Complete audit trail through queue logs

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.

About Us

Dynexcel: Your trusted partner for cutting-edge ERP solutions. We specialize in seamless implementation and optimization services, helping businesses streamline operations and drive growth. Transform your business with us today.

Email Support
support@dynexcel.com
WhatsApp
wa.me/923001234567
Support Ticket
https://www.dynexcel.com/helpdesk/customer-care-1
YouTube Channel
youtube.com/@dynexcel
Documentation
docs.dynexcel.com/zkteco
Developer Website
🌐
Website
https://www.dynexcel.com
Availability
Odoo Online
Odoo.sh
On Premise
Odoo Apps Dependencies • Attendances (hr_attendance)
• Employees (hr)
• Discuss (mail)
Lines of code 891
Technical Name de_zkteco_attend
LicenseOPL-1
Websitehttps://dynexcel.com 
Odoo Proprietary License v1.0

This software and associated files (the "Software") may only be used (executed,
modified, executed after modifications) if you have purchased a valid license
from the authors, typically via Odoo Apps, or if you have received a written
agreement from the authors of the Software (see the COPYRIGHT file).

You may develop Odoo modules that use the Software as a library (typically
by depending on it, importing it and using its resources), but without copying
any source code or material from the Software. You may distribute those
modules under the license of your choice, provided that this license is
compatible with the terms of the Odoo Proprietary License (For example:
LGPL, MIT, or proprietary licenses similar to this one).

It is forbidden to publish, distribute, sublicense, or sell copies of the Software
or modified copies of the Software.

The above copyright notice and this permission notice must be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.

Please log in to comment on this module

  • The author can leave a single reply to each comment.
  • This section is meant to ask simple questions or leave a rating. Every report of a problem experienced while using the module should be addressed to the author directly (refer to the following point).
  • If you want to start a discussion with the author or have a question related to your purchase, please use the support page.