McodeyHR logo
Home Sign in

Workflow

Device connection guide

Connect K60 / biometric devices via HR Sync Agent (pull) or ADMS cloud push

Overview

Mcodey HR supports two ways to get attendance from biometric devices (e.g. ZKTeco K60) into the cloud: (1) HR Sync Agent — an office PC pulls punches over LAN and uploads via API; (2) ADMS cloud push — ADMS-capable devices push ATTLOG directly to Mcodey over the internet (no office PC). Device registration and PIN enrollments are the same for both paths.

Choose a connection method

Pick one path (or use only one as primary) based on your device firmware and branch setup.

HR Sync Agent (pull)

Install the desktop agent on an office PC. It connects to the device on LAN port 4370 and syncs to /api/v1. Requires Business or Pro (api_access) and agent.sync permission.

Best for — non-ADMS devices, LAN-only setups, branches with an always-on office PC

ADMS cloud push

Devices with ZKTeco ADMS / cloud server firmware push ATTLOG to {your-domain}/iclock over HTTPS. No Sync Agent or office PC. Attendance source is recorded as adms.

Best for — ADMS-ready models (ADMS badge on hardware catalog), internet-connected devices, branches without a dedicated PC

Sync Agent architecture

┌─────────────┐     LAN      ┌──────────────┐    HTTPS    ┌─────────────────┐
│ K60 / MB20  │─────────────▶│ Office PC    │────────────▶│ Mcodey HR API   │
│ 192.168.x.x │   port 4370  │ Sync Agent   │  /api/v1    │ attendances/sync│
└─────────────┘              └──────────────┘             └─────────────────┘

ADMS cloud push architecture

┌─────────────┐   internet    ┌─────────────────────────┐
│ K60 (ADMS)  │──────────────▶│ Mcodey HR /iclock/cdata │
│ SN + pushkey│   HTTPS       │ ATTLOG → attendance     │
└─────────────┘               └─────────────────────────┘

Prerequisites

  • Active company license
  • Device registered in web admin with correct serial number
  • Every employee PIN mapped in Enrollments
  • Sync Agent path — Business or Pro (api_access), agent.sync user, office PC, device LAN IP + port 4370
  • ADMS path — ADMS firmware, internet on device, matching SN and device push key (device_token)

Roles involved

These roles are typically involved in device setup:

  • Company owner / HR manager — register devices and manage enrollments
  • Attendance operator — update device IP, check sync logs, manual attendance
  • Branch manager — review branch attendance
  • IT / office staff — Sync Agent install (path A) or ADMS menu on device (path B)

Workflows

Steps 1–2 (register device + enrollments) are shared. Then follow the path that matches your device.

Path A — HR Sync Agent

When not using ADMS — requires office PC and Sync Agent.

1. Register device in web admin

Admin panel → Devices → Create

  1. Enter name, branch, serial number, and device type (K60/MB20)
  2. Set LAN IP address and port 4370
  3. Set comm password if the device uses a non-default key — otherwise leave default (0)
  4. Save and confirm the device appears in the list

2. Device enrollments (PIN → employee)

Map each device user ID to a cloud employee.

  1. Devices → select device → Enrollments
  2. Enter device user ID (PIN) shown on the device — e.g. 1, 101
  3. Select the linked employee
  4. Enroll fingerprint/face on the device and verify the PIN on screen
  5. Unmapped PINs cause sync failed — unknown PIN errors

3. Install HR Sync Agent (office PC)

  1. Obtain Mcodey HR Sync Agent for Windows / macOS / Linux
  2. Install on an office PC on the same LAN as the device
  3. Open app and set API base URL — e.g. https://hr.mcodey.com/api/v1
  4. Sign in with an HR account that has agent.sync (not Super Admin)
  5. Settings → agent name and auto-sync interval (default 5 minutes)

4. First sync and verification

  1. Punch once on the device for testing
  2. Sync Agent → Sync all
  3. Web admin → Sync logs — status success or partial
  4. Web admin → Attendance — row with source Agent
  5. Devices list — last_sync_at updated

5. Configure auto-start (recommended)

If the agent is closed, punches will not sync.

  1. Windows: Startup folder or Task Scheduler at log on
  2. macOS: LaunchAgent
  3. Linux: autostart .desktop
  4. Keep the office PC on during business hours

6. After adding a new employee

  1. HR adds employee record
  2. Enroll on device and note PIN
  3. Web → Devices → Enrollments — link PIN to employee
  4. Test punch → sync → verify in Attendance

7. After device IP changes (Sync Agent)

  1. Set new IP on the device
  2. Web admin → Devices → Edit — update IP only (agent pulls config from API)
  3. Sync Agent → Sync all to verify connectivity

Path B — ADMS cloud push

For ADMS-capable devices — the device pushes directly to the cloud. ADMS URLs appear on Devices → Edit.

1. Prepare device in web admin for ADMS

ADMS panel appears when serial number and push key exist.

  1. Devices → Create/Edit — enter serial number matching device SN
  2. Save and note device token (push key) — ADMS panel shows server URL and cdata endpoint
  3. Complete Enrollments for all PINs

2. Configure ADMS on the device

ZKTeco menu → Communication → Cloud Server / ADMS

  1. Server URL — from Mcodey admin ADMS panel (e.g. https://hr.mcodey.com/iclock)
  2. Serial (SN) — must match devices.serial_number in web admin
  3. Push key / password — use device push key (device_token)
  4. Verify internet and heartbeat (getrequest) in sync logs

3. First punch and verification

  1. Punch once on the device
  2. Web admin → Sync logs — ADMS batch success or partial
  3. Web admin → Attendance — row with source adms
  4. Devices — last_sync_at / online status updated

4. Do not run both ADMS and Sync Agent as primary

Duplicate punches may be skipped — choose one primary path.

  1. ADMS — no office PC needed; SN, push key, and enrollments must be correct
  2. Agent — disable ADMS cloud menu or use only one active path

Checklists

A — Cloud (HR admin)

  • Business or Pro package
  • HR user has agent.sync
  • Device created with branch, serial, type
  • IP and port 4370 correct
  • All employee enrollments complete
  • Test punch works on device

B — Office PC (Sync Agent)

  • PC on same LAN as device
  • Sync Agent installed and login OK
  • Manual Sync all → accepted ≥ 1 or no new records
  • Web sync logs show success
  • Web attendance shows Agent source rows
  • Auto-start configured

C — ADMS cloud push

  • Device has ADMS / cloud server firmware
  • Web serial and push key correct
  • Device menu — server URL, SN, pushkey set
  • Internet connectivity on device
  • Enrollments complete
  • Test punch → sync logs + attendance (source adms)

Troubleshooting

Symptom Fix
Agent login 403 — API access Upgrade to Business or Pro (api_access required)
Agent login 403 — permission Assign HR manager, branch manager, or attendance operator role
Agent login 403 — license Renew company license in Billing
Cannot connect to device (timeout) Check IP, port 4370, comm password, firewall — PC and device must share LAN
Sync failed — unknown PIN Add Devices → Enrollments for that device_user_id
Sync skipped only Normal — punch already in cloud (duplicate dedup)
Attendance not appearing Is agent running? → Sync all → check sync logs and enrollments
No sync overnight (Agent) Agent closed or PC off — enable auto-start and power schedule
ADMS push rejected — invalid push key Match device pushkey/password to device token on Devices → Edit
ADMS push rejected — unknown serial Device SN must match devices.serial_number in web admin
ADMS returns OK:0 only Non-ATTLOG table or failed enrollment — check sync logs
Duplicates with Agent + ADMS Use one primary path — duplicates are skipped by design

Day-to-day operations

  • Missing attendance — Agent path: agent running? → Sync all; ADMS path: check internet and pushkey
  • New employee — enroll on device + web Enrollments
  • New device — register in web; one PC can sync multiple devices
  • IP change — Devices → Edit only
  • API offline — agent queues locally and retries on next sync
  • Monitor in web — Devices (last_sync_at), Sync logs, failed batch notifications
Attendance operator guide → ← Role guide