| Availability |
Odoo Online
Odoo.sh
On Premise
|
| Odoo Apps Dependencies |
•
Attendances (hr_attendance)
• Time Off (hr_holidays) • Employees (hr) • Discuss (mail) • Calendar (calendar) |
| Lines of code | 10197 |
| Technical Name |
dotbd_hr_zk_attendance_suite |
| License | OPL-1 |
| Website | https://dotbdsolutions.com |
| Versions | 17.0 18.0 19.0 |
| Availability |
Odoo Online
Odoo.sh
On Premise
|
| Odoo Apps Dependencies |
•
Attendances (hr_attendance)
• Time Off (hr_holidays) • Employees (hr) • Discuss (mail) • Calendar (calendar) |
| Lines of code | 10197 |
| Technical Name |
dotbd_hr_zk_attendance_suite |
| License | OPL-1 |
| Website | https://dotbdsolutions.com |
| Versions | 17.0 18.0 19.0 |
ZKteco HR Attendance Suite
Complete Biometric Integration (Enhanced)
v19.0.7.0.0 - Now with ADMS Cloud Push Protocol & Hybrid Connection Modes!
Transform Your Attendance Management
The most comprehensive attendance management solution for Odoo 19, featuring seamless ZKteco biometric device integration, powerful real-time analytics dashboard, intelligent anomaly detection, and enterprise-grade reporting capabilities. Perfect for businesses of all sizes looking to automate attendance tracking and gain valuable workforce insights.
Interactive Attendance Dashboard
A completely new visual command center for your workforce attendance — real-time, colour-coded, and actionable at a glance.
Smart Holiday Detection
The dashboard automatically detects if today is a public holiday and displays a prominent banner with the holiday name. It also shows the next 2 upcoming holidays so your team is always informed in advance.
Today's Live Overview
Six real-time stat cards show Total Employees, Present, Absent, On Leave, Late Today, and Total Fine — all updated live with department and employee filters applied instantly.
Colour-Coded Monthly Calendar
A full monthly grid per employee shows every day as Present (), Absent (A), Leave with short code (CL, SL, OHâ¦), Weekend (W), or Holiday (H). Late days are highlighted in a distinct colour.
Leave Type Short Codes
Instead of a plain "L", each leave day shows its exact type code — CL (Casual Leave), SL (Sick Leave), OH (Official Holiday), and more. Codes are fully customisable from the Leave Type configuration.
Employee Monthly Summary
Click any employee row to open a detailed summary panel showing their monthly totals: days Present, Absent, on Leave, Weekend, Holiday, and Late — all in one compact card with their photo and job title.
Configurable Weekend Days
Weekend days are no longer hard-coded. Choose any combination of days (e.g. Friday + Saturday for Bangladesh) from Attendance Settings. The dashboard, calendar, and reports all respect your configuration.
Holiday Banners & Stat Cards
Employee Summary Panel
Monthly Calendar with Leave Codes (CL / SL / OHâ¦)
Configurable Weekend Days Setting
Why Choose This Suite?
100% PyZK Integration
Direct device communication without third-party APIsAuto Mode NEW
Intelligent check-in/check-out that prevents HR mistakesLive Capture NEW
Real-time attendance monitoring as events happenAdvanced Dashboard
Interactive Chart.js visualizations & analyticsDoor Control NEW
Remote door unlock with configurable durationAudio Feedback NEW
Custom sounds for check-in, check-out & errorsLCD Messages NEW
Personalized welcome/goodbye on device screenDuplicate Prevention
Ignore repeated punches within time windowAuto Time Sync NEW
Device clock auto-corrected before every downloadRobust Error Logs NEW
Pinpoint EXACTLY why a punch failed (Savepoints active!)Three Powerful Connection Modes
Choose the perfect connection strategy for your deployment architecture.
Direct Mode (PyZK)
Best for local networks or VPN connections where Odoo can directly reach the device IP.
- 100% hardware control
- Real-time Live Capture
- LCD & Voice messages
- Door access control
Cloud Mode (ADMS)
Best for SaaS/Cloud Odoo instances. The device pushes data to Odoo over HTTP(S). No port forwarding needed!
- Perfect for remote sites
- Bypass firewalls easily
- Auto-registers devices
- Remote Fingerprint Enrollment
Hybrid Mode
The ultimate flexibilty. Uses ADMS for reliable attendance push, and PyZK for deep hardware control.
- Our Unique Offering!
- Best of both worlds
- Automatic attendance sync
- Full hardware capabilities
Four Intelligent Attendance Modes
Choose how your module processes each punch. Configurable per device — mix and match across your organization.
Traditional Mode
Uses the device's punch type directly.
- Punch type 0 = Check-in
- Punch type 1 = Check-out
- Device must be configured correctly
- Multiple records per day possible
Auto Mode
Ignores device punch type. Auto-alternates.
- 1st punch → Check-in
- 2nd punch → Check-out
- 3rd punch → Check-in again
- Prevents HR mistakes
Auto Per Day NEW
One attendance record per employee per day.
- First punch of day = Check-in
- Last punch of day = Check-out
- Middle punches update check-out
- Auto-closes missed check-outs
08:55 → Check-in
12:00 → Check-out updated
13:00 → Check-out updated
17:30 → Final check-out
Traditional Per Day NEW
Device punch type respected, but max one in/out per day.
- Only first check-in counts
- Only first check-out counts
- Duplicate punches ignored
- Auto-closes missed check-outs
Smart Edge Case Handling (Per-Day Modes)
Module auto-closes yesterday's record at 23:59:59, then creates today's new check-in normally.
In Auto Per Day, every punch after the first updates the check-out. The last punch always wins.
Uses the device's configured timezone to determine "today" — so midnight is always correct for your location.
PyZK Download, Live Capture, and ADMS Cloud Push all support all four attendance modes.
Robust Error Logging & Transaction Protection
Enterprise-grade resilience. Every failed punch is logged with the exact reason — your bulk downloads never crash midway through.
Database Savepoint Protection
Each attendance record is processed inside an isolated database savepoint. If one record fails (overlap, invalid timestamp, missing employee), only that record is rolled back — the rest continue processing normally.
- Downloads 10,000+ records without crashing
- Bad records are skipped, not fatal
- Works for both PyZK & ADMS modes
- Cron jobs complete even with errors
Common Reasons a Punch May Fail (All Auto-Logged)
Employee already has an active shift covering the punch timestamp. Odoo rejects duplicate overlap.
Device sent a corrupted or impossible date (e.g. Jan 1, 1970 after a power reset).
Employee was removed from Odoo but still punches on the biometric device.
Device user ID not linked to any Odoo employee. Logged as a warning for admin review.
Quick Setup Guide
Get your ZKTeco devices connected in minutes. Choose the method that matches your network.
Direct Mode (PyZK) Setup
For local network / VPN deployments-
Install the PyZK library on your Odoo server:
pip3 install pyzk
- Find the device IP: On the device menu, go to COMM → Ethernet → IP Address.
- In Odoo, go to Attendances → ZK Devices → Create.
-
Fill in:
- Name: e.g. "Main Entrance"
- IP Address: The device IP (e.g. 192.168.1.201)
- Port: 4370 (default)
- Connection Mode: Direct (PyZK)
- Attendance Mode: Choose your preferred mode
- Click "Test Connection". If successful , you're ready!
- Map employees: Set each employee's ZK Device User ID in their HR profile (must match the ID on the device).
- Click "Download Attendance" to fetch records, or enable the Scheduled Action for automatic downloads.
Cloud Mode (ADMS) Setup
For Odoo.sh, cloud hosting, or remote sites-
Ensure your Odoo is accessible via a public URL
(e.g.
https://mycompany.odoo.com). -
On the ZKTeco device, go to COMM → Cloud Server
Setting:
- Enable: Yes
- Server Address: your-odoo-domain.com
- Server Port: 443 (HTTPS) or 80 (HTTP)
- Restart the device. It will automatically connect to Odoo and register itself.
- In Odoo, go to Attendances → ZK Devices. You'll see the device auto-created with its serial number.
-
Configure the device record:
- Connection Mode: Cloud (ADMS) or Hybrid
- Attendance Mode: Choose your preferred mode
- Map employees: Set each employee's ZK Device User ID to match the device.
- Done! Attendance is pushed automatically in real-time whenever an employee punches.
Hybrid Mode — Best of Both Worlds
Want automatic attendance push (ADMS) plus hardware control like LCD messages, voice feedback, and door unlock (PyZK)? Set Connection Mode = Hybrid. The device pushes data via ADMS, while Odoo uses PyZK for hardware features. Requires both network paths to be available.
Troubleshooting & Common Issues
This happens when the device sends a punch for a user ID that is not linked to any employee in Odoo.
- Go to HR → Employees in Odoo
- Open or create the employee record
- Set the "Device ID Number" field to match the user ID on the biometric device
- Save. Next punch will be processed automatically!
The device connects but doesn't show in the device list.
- First create the device in Odoo with Connection Mode = Cloud (ADMS)
- Set the Device Serial Number to match the device's serial (shown on device menu)
- Restart the device — it will auto-match on next heartbeat
Each user enrolled on the biometric device has a unique ID number.
- On Device: Menu → User Mgt → All Users → select user → see ID
- In Odoo Log: Check the server log for the error message — it shows the exact Device ID Number to use
- Example log:
No employee found with Device ID Number '6666'→ Set employee's Device ID = 6666
In ADMS mode, the device clock is automatically synced from the server on every heartbeat.
- Device time = Server Time. If you manually change time on the device, it will revert within seconds.
- To change your device time, you must change your server time.
Employee Mapping Guide
Properly mapping employees is crucial for a smooth experience and to avoid duplicate records.
Recommended Workflow:
- Create Employee in the Odoo HR module first.
- Set ZK Device User ID in the employee's Biometric settings tab.
- Connect the Device to Odoo.
- Download Attendance: Now, attendance records will sync perfectly without duplicates!
For PyZK Mode
If your Odoo database has no employees yet but the device contains all employee records, you can download users directly from the device to auto-create them in Odoo.
For ADMS Mode
ADMS cannot download users from the device. You MUST create the employees in Odoo and map their Device IDs before downloading attendance.
Core Features
Advanced Biometric Integration
- Multi-device support (uFace 202, 800, K40, ZK4500)
- Face & fingerprint recognition
- Auto Check-in/Check-out Mode - Prevents HR mistakes
- Duplicate Punch Prevention - Configurable window
- Traditional Mode for backward compatibility
- Automatic sync with configurable intervals
- Centralized device management
- Auto employee mapping
Real-time Analytics Dashboard
- Interactive Chart.js visualizations
- Smart date filters (Today/Week/Month/Year)
- Live attendance metrics & KPIs
- Instant anomaly alerts
- Department analytics
- Export capabilities
- Employee time-off tracking
- Manual attendance monitoring
Intelligent Anomaly Detection
- Missing check-in/out detection
- Duplicate punch identification
- Attendance violation tracking
- Automated categorization
- Compliance reporting
- Issue resolution workflow
- Invalid time entry detection
- Audit trail support
Late Check-in Management
- Configurable grace periods
- Automatic penalty calculation
- 4-state approval workflow
- Payroll integration
- Late analytics dashboard
- Email notifications
- Penalty waiver system
- Department-wise tracking
Professional Attendance Sheets
- Calendar-style monthly layout
- Color-coded status indicators
- PDF & Excel export
- Individual or combined reports
- Rich statistics & rankings
- Leave & holiday integration
- Work hours calculation
- Attendance rate tracking
Comprehensive Reporting
- Summary & detailed reports
- Late check-in penalty reports
- Anomaly compliance reports
- Professional Excel export
- Print-ready PDF generation
- Custom date range filtering
- Department analytics
- Employee performance metrics
Compatible ZKTeco Devices by Connection Mode
PyZK / Direct Method Supported
Almost all ZKTeco network devices support Direct PyZK.
- F Series: F18, F16, F19
- K Series: K14, K20, K28, K30, K40, K50, K60
- uFace Series: uFace 202, uFace 402, uFace 800, uFace 302
- iClock Series: iClock260, iClock360, iClock560, iClock680, iClock700, iClock880, iClock990
- MA Series: MA300, MA500
- MB Series: MB10, MB10VL, MB160, MB200, MB360, MB460, MB560, MB860
- Card Terminals: SC405, SC700
- Standalone: SilkFP-101TA, MultiBio 700
ADMS / Cloud Method Supported
Requires firmware with ADMS activated.
- SpeedFace Series: SpeedFace-V5L, SpeedFace-H5, SpeedFace-M4
- ProFace Series: ProFace X, ProFace Plus
- Green Label / G Series: G1, G2, G3, G4
- IN Series: in01-A, IN05
- SilkID: Silk104
- Biometrics Models: uFace800 Plus, F22, K40 Pro (if ADMS enabled)
- Access Panels: inBio160, inBio260, inBio460
Hybrid Method Supported
Devices that support BOTH PyZK and ADMS.
- Highest Compatibility:
- uFace 800 Plus: Incredible hardware allowing real-time TCP/IP alongside ADMS.
- SpeedFace V5L: Modern Visible Light facial tech.
- F22: Ultra-thin fingerprint terminal.
- G3/G4: Multi-biometric identification.
- Any ADMS Device on local LAN: Any device from the ADMS list that is also accessible locally (no NAT/firewall blocking) can use Hybrid Mode!
Connection Requirements
- Device must support TCP/IP connection
- Device must use Standalone SDK Protocol
- Device firmware should be up-to-date
- LAN: (same network)
- VPN: (Site-to-Site for cloud server)
- Port Forwarding: (with static IP)
Getting Started Guide
1. Configure Your ZKteco Device
Access the Attendance module from the main menu
Navigate to Biometric Devices section
Click "New" to add a new device
Enter device IP, port, and password
Test connection to verify setup
2. Advanced Device Management NEW
Configuration Tab: Connection details, attendance modes (Auto/Traditional), duplicate prevention settings, and location information
Capacity & Health: Monitor user capacity, fingerprint enrollment, face templates, and attendance record storage
Live Monitoring: Real-time attendance capture settings with instant notifications and event statistics
Messages & Audio: LCD message customization, welcome/goodbye messages, and audio feedback with 55+ voice options
Door Control: Remote door unlock, lock status monitoring, and configurable unlock duration with security warnings
Users Tab: Sync employees to device, backup biometric templates, verify employee data, and automatic enrollment
Status Bar: Quick overview of device status, attendance records count, enrolled users, and backup templates
3. Attendance Overview & Working Schedules
View real-time attendance records and monitoring
Configure working schedules for employees
Assign schedules and link ZK User IDs
4. Attendance Settings & Rules
Configure tolerance time and validation rules
Setup late check-in penalties and grace periods
Configure automated cron jobs and actions
5. Analytics Dashboard
Interactive charts and real-time KPIs
Comprehensive attendance statistics
Department-wise attendance analysis
Employee Time Off & Manual Entries: Track leave dates, monitor manual attendance with missing check-out alerts
5b. Attendance Dashboard — See Everything at a Glance
A live, interactive attendance view built right into your Odoo. No reports to run — just open the dashboard and instantly know who is in the office, who is late, who is absent, and who is on leave — all in one screen.
The full Attendance Dashboard — today's numbers, monthly calendar, filters, and employee details all in one place
Today's Overview Cards
At the very top, four cards instantly show you how many employees are total, how many are present, absent, and on leave — right now, today. When late penalties are enabled, two extra cards appear showing today's late count and total fine amount.
One-Click Status Filters
Click Present, Absent, Late, or On Leave buttons to instantly show only the employees matching that status. The count on each button always reflects today's numbers. Click again to clear the filter.
Full Monthly Calendar
See every employee's attendance for the entire month in a scrollable grid. Each day shows a colour-coded status: green check for present, red A for absent, amber check for late, L for leave, W for weekend, and H for public holiday. Summary totals appear at the end of each row.
Click Any Employee for Their Summary
Click any employee row to highlight it and reveal a personal summary card showing their exact monthly counts for Present, Absent, Leave, Weekend, Holiday, and Late days. Click the same row again — or the close button — to dismiss it.
Top Rankings in One Click
Four sort buttons let you instantly re-order the list: Top Present puts the most-present employees first, Top Absent shows who missed the most days, Top Late surfaces the most frequently late arrivals, and Top Leave highlights who took the most time off.
Role-Based Access
Managers and HR officers see the full team. Regular employees who open the dashboard see only their own attendance — no one else's data is ever visible to them. Filters and sort buttons work the same way for everyone within their allowed scope.
6. Anomaly Detection & Analysis
Automatic anomaly identification
Detailed anomaly breakdown
Statistical analysis of issues
Compliance and audit reports
7. Reports & Exports
Multiple report generation options
Custom date range selection
Advanced filtering options
Visual anomaly trends
Excel export functionality
Calendar-style attendance view
Comprehensive daily breakdown
Monthly attendance summary
What's New in This Version
Auto Check-in/Check-out Mode RECOMMENDED
- Intelligent Processing: Automatically determines check-in/check-out based on last attendance
- Prevents HR Mistakes: Ignores device punch type completely
- How it works: First punch → Check-in, Second → Check-out, alternates automatically
- Zero Configuration: No device setup needed
Real-Time Live Capture
- Instant attendance capture as events occur
- No more polling delays
- Immediate notifications to relevant users
- LCD and audio feedback triggered automatically
Device Health Monitoring
- Track firmware version and device info
- Monitor storage capacity and usage
- User and biometric template statistics
- Network information tracking
Door Access Control
- Remote door unlock from Odoo
- Configurable unlock duration
- Lock status monitoring
- All actions logged in chatter
Intelligent Time Sync & Auto-Correction ENHANCED
- Auto-Sync Before Download: Device clock is automatically checked and corrected before every attendance download — manual or cron
- Drift Detection: Detects clock drift >30 seconds and auto-corrects — no manual intervention needed
- Cron-Safe Timezone: Stores effective timezone on device record — cron jobs no longer depend on user timezone setting
- Flexible Options: Sync using Odoo User Time, Server UTC, Custom Timezone, or Manual override
- Live Capture Ready: Auto-sync also runs before live capture starts
- Visible Status: "Current Device TZ" field shows exactly which timezone the device is running in
Identity Protection NEW
- Safe Sync Topology: Protects existing face/fingerprint data during sync
- Ghost Prevention: Stops cross-assignment of employee IDs
- Active Tracking: Logs unmapped device users into Odoo for HR review
Multi-Device Global Sort NEW
- Two-Phase Download: All devices downloaded first, then all punches processed together in true chronological order
- Download Button Downloads All: Clicking Download on any device automatically downloads all devices — no need to click each one
- No More Duplicate Records: Employees registered on multiple devices no longer get double attendance records
- All Modes Supported: Works correctly for Auto, Auto Per Day, Traditional, and Traditional Per Day
Odoo Punch Type Visibility NEW
- New Column in Attendance Analysis: "Odoo Punch Type" shows whether the module processed a punch as Check In or Check Out — separate from the device's reported punch type
- Chronological Fix: Punches now always processed in time order — fixes the bug where check-out was recorded before check-in
- Full Traceability: Every raw punch record now links directly to its generated hr.attendance record
- Live Capture UTC Fix: Live capture timestamps now correctly converted from device local time to UTC before storage
Enterprise Features
Integration & Automation
- Time Off (hr_holidays) integration
- Public holidays detection
- Working calendar respect
- Overtime tracking
- Payroll deductions (optional)
- Automated scheduled actions
Security & Compliance
- Multi-company support
- Role-based access control
- Complete audit trail
- Data security & encryption
- Compliance reporting
- GDPR ready
What's Included
Complete Package
- Full source code with AGPL-3 license
- Comprehensive documentation
- Installation guide
- Sample data for testing
Support & Updates
- 30 Days premium email support
- 24-48 hour response time
- Free bug fixes
- Security patches included
Frequently Asked Questions
- VPN (Recommended): Set up a Site-to-Site VPN between your office network and your Cloud Server.
- Port Forwarding: Forward the device port (default 4370) on your office router to the public internet (requires Static IP at office).
Compatible models include: uFace 202, uFace 800, iClock series, K40, K14, MB10VL, F18, UA300, ZK4500, and more.
Simple test: If your device works with the old ZKTime.net 3.0 software, it will work with this module!
Support & Resources
Need help? We're here for you!
Dot BD Solutions Limited
Copyright © 2025 Dot BD Solutions Limited. All rights reserved.
Author: Rafiur Rahman Rafit
Licensed under OPL-1
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