User Manual - HR Attendance Fingerspot¶

Modul: HR Attendance Fingerspot Versi: 18.0.1.3.1 Odoo: Community Edition 18

Daftar Isi¶

1. Pendahuluan
2. Hak Akses User
3. Setup Awal
4. Konfigurasi Mesin
5. Mapping Employee ke PIN
6. Pull Data Attendance
7. Sync Attendance
8. Webhook (Real-time Data)
9. Menu Attendance
10. Menu Raw Attlog
11. Menu Webhook Logs
12. Menu Sync Logs
13. Koreksi Manual oleh Admin
14. Cron Job (Auto Pull & Sync)
15. Tracking / Audit Log
16. Troubleshooting

1. Pendahuluan¶

Modul ini mengintegrasikan mesin absensi Fingerspot dengan Odoo melalui Fingerspot Cloud API. Data absensi ditarik dari cloud, disimpan di tabel raw, kemudian diproses menjadi data attendance valid (check-in/check-out per hari per karyawan).

Alur Data¶

Fingerspot Cloud API          Fingerspot Device
        |                            |
        | [Pull Attlog]              | [Webhook - real-time]
        v                            v
  Raw Attlog (tabel temporary)  ←────┘
  - Semua data scan mentah
  - Bisa ratusan record/hari
        |
        | [Sync Attendance]
        |   (hanya PIN yang sudah di-link ke employee)
        v
  Attendance (tabel valid)      →  Sync Log (audit trail)
  - 1 record per karyawan per hari
  - Check In  = scan paling AWAL (MIN) di hari itu
  - Check Out = scan paling AKHIR (MAX) di hari itu
  - Jika hanya 1 scan → Check In = Check Out
  - Total Hours otomatis dihitung

Data bisa masuk melalui 2 jalur: 1. Pull - tarik data historis dari Fingerspot Cloud API (maks 2 hari per request) 2. Webhook - terima data real-time langsung dari mesin Fingerspot

2. Hak Akses User¶

Modul ini memiliki 3 level akses:

Cara Set Hak Akses¶

1. Masuk Settings > Users & Companies > Users
2. Klik user yang ingin diatur
3. Scroll ke bagian Fingerspot
4. Pilih level: Readonly / Administrator
5. Klik Save

Catatan: Semua internal user secara otomatis mendapat akses "Own Reader" — bisa melihat data attendance miliknya sendiri tanpa perlu set permission apapun. Ini sama seperti behavior default modul hr_attendance bawaan Odoo.

3. Setup Awal¶

Prasyarat¶

• Akun Fingerspot Developer (https://developer.fingerspot.io)
• Cloud ID mesin (didapat dari mesin Fingerspot yang sudah terdaftar di cloud)
• API Token (Bearer token dari akun developer Fingerspot)

Langkah Install¶

1. Copy folder modul hr_attendance_fingerspot ke folder addons Odoo
2. Restart Odoo server
3. Masuk Odoo > Apps > hapus filter "Apps" > cari "fingerspot"
4. Klik Install

4. Konfigurasi Mesin¶

Menambah Mesin Baru¶

1. Masuk menu Fingerspot > Machines
2. Klik New
3. Isi field berikut:

1. Klik Save
2. Copy Webhook URL dan set di dashboard Fingerspot Cloud (lihat bagian Webhook)

Tombol Aksi di Form Mesin¶

Smart Button¶

5. Mapping Employee ke PIN¶

Agar data attendance ter-sync ke karyawan, PIN di mesin Fingerspot harus di-mapping ke employee. Sync hanya memproses PIN yang sudah di-link ke employee — PIN tanpa employee akan di-skip (data raw tetap tersimpan untuk sync ulang nanti).

Cara Setting¶

1. Masuk Employees > [pilih karyawan]
2. Klik tab Fingerspot
3. Isi field Fingerspot PIN dengan nomor PIN karyawan di mesin
4. Klik Save

Penting: PIN harus sama persis dengan yang terdaftar di mesin Fingerspot. Gunakan tombol Get All PINs di form mesin untuk melihat daftar PIN yang tersedia.

Tips¶

• Jika belum tahu PIN karyawan, buka form Mesin > klik Get All PINs > lihat daftar di tab Notes
• Satu PIN hanya boleh di-assign ke satu karyawan
• Setelah PIN di-link ke employee, jalankan Sync Attendance untuk memproses data raw yang sebelumnya di-skip

6. Pull Data Attendance¶

Pull adalah proses menarik data scan mentah dari Fingerspot Cloud API ke tabel Raw Attlog.

Pull Manual¶

1. Masuk Fingerspot > Machines
2. Buka form mesin yang ingin di-pull
3. Klik tombol Pull Attlog
4. Sistem akan menarik data dari tanggal Last Pull Date sampai hari ini
5. Notifikasi muncul: "X raw attendance records pulled"

Catatan¶

• Pull pertama kali: data ditarik untuk hari ini saja
• Pull berikutnya: data ditarik dari tanggal terakhir pull
• Data duplikat otomatis di-skip (berdasarkan kombinasi machine + pin + scan_date)
• Field Last Pull Date di form mesin akan ter-update otomatis
• API Fingerspot membatasi maksimal 2 hari per request — sistem otomatis membagi (chunk) periode panjang menjadi bagian-bagian 2 hari

7. Sync Attendance¶

Sync adalah proses mengolah data Raw Attlog menjadi data Attendance valid.

Logika Sync¶

Untuk setiap karyawan (PIN) per hari: - Check In = waktu scan paling awal (MIN) di hari tersebut - Check Out = waktu scan paling akhir (MAX) di hari tersebut - Jika hanya ada 1 scan di hari itu → Check In = Check Out, Worked Hours = 0:00 - Total Hours = selisih Check Out - Check In (otomatis dihitung)

Syarat Sync¶

• PIN harus sudah di-link ke employee (via Fingerspot PIN di form employee)
• PIN tanpa employee akan di-skip — data raw tetap tersimpan (is_synced = False)
• Setelah PIN di-link, jalankan sync ulang dan data akan terproses

Sync Manual (via Wizard)¶

1. Masuk Fingerspot > Machines
2. Buka form mesin
3. Klik tombol Sync Attendance
4. Popup wizard muncul dengan:
5. Date From — default: tanggal 1 bulan ini
6. Date To — default: hari ini
7. Ubah periode jika perlu, lalu klik Sync Now
8. Wizard menampilkan hasil:
9. Banner hijau jika sukses, kuning jika ada error
10. Synced — jumlah record yang berhasil di-sync
11. Errors — jumlah record yang gagal
12. Error Details — detail error per PIN/tanggal (jika ada)

Pull & Sync Sekaligus¶

1. Klik tombol Pull & Sync di form mesin
2. Wizard muncul dengan pilihan tanggal (Date From / Date To)
3. Klik Pull & Sync Now
4. Wizard menampilkan hasil:
5. Pulled — jumlah raw record yang ditarik
6. Synced — jumlah record yang berhasil di-sync
7. Errors — jumlah record yang gagal

Penanganan Error Saat Sync¶

• Jika satu record gagal (misal data corrupt), record lain tetap diproses
• Record yang gagal di-skip dan dilaporkan di Error Details
• Record yang gagal tidak ditandai sebagai synced, sehingga bisa di-retry

Catatan¶

• Hanya data raw yang belum di-sync yang akan diproses
• Data raw yang sudah di-sync ditandai dengan flag Synced = True
• Jika ada data raw baru untuk tanggal yang sudah ada attendance-nya, sistem akan update jika ditemukan MIN lebih awal atau MAX lebih akhir
• Record yang sudah dikoreksi manual (Manually Corrected = True) tidak akan di-overwrite oleh sync
• Setiap eksekusi sync otomatis tercatat di Sync Log (lihat bagian Sync Logs)

8. Webhook (Real-time Data)¶

Selain Pull (tarik data dari cloud), modul ini juga mendukung webhook untuk menerima data secara real-time langsung dari mesin Fingerspot.

Cara Kerja Webhook¶

1. Mesin Fingerspot mengirim data scan ke Odoo via HTTP POST
2. Data diterima di endpoint /fingerspot/webhook
3. Data otomatis disimpan ke Raw Attlog dan di-log ke Webhook Log

Setup Webhook¶

1. Buka form mesin di Fingerspot > Machines
2. Copy Webhook URL (klik icon copy di sebelah field)
3. Login ke Fingerspot Cloud Dashboard (developer.fingerspot.io)
4. Set URL webhook di pengaturan mesin dengan URL yang di-copy
5. Selesai — data akan masuk otomatis setiap ada scan di mesin

Tipe Webhook yang Didukung¶

Catatan Penting¶

• Webhook URL harus bisa diakses dari internet (public URL)
• Jika Odoo diakses via reverse proxy, pastikan path /fingerspot/webhook di-forward dengan benar
• Untuk setup multi-database, pastikan dbfilter dikonfigurasi di odoo.conf agar Odoo tahu database mana yang dituju
• Semua data webhook yang masuk tercatat di Webhook Logs untuk audit trail

9. Menu Attendance¶

Menu Fingerspot > Attendance menampilkan data attendance yang sudah divalidasi. Tampilannya mengikuti style default modul Attendance Odoo.

Kolom Utama¶

Kolom Optional (klik icon kolom untuk menampilkan)¶

Pivot View¶

Tersedia pivot view untuk analisis attendance: - Baris: Department > Employee - Kolom: Bulan - Measure: Total Hours

Graph View¶

Tersedia graph view (bar chart): - Sumbu X: Department - Measure: Total Hours

Filter & Group By¶

Filter: - Today - data hari ini - This Week - data minggu ini - This Month - data bulan ini - No Check Out - karyawan yang belum check out - Synced / Not Synced - berdasarkan status

Group By: - Employee - kelompokkan per karyawan - Department - kelompokkan per departemen - Manager - kelompokkan per atasan - Date - kelompokkan per tanggal - Machine - kelompokkan per mesin - Status - kelompokkan per status sync

10. Menu Raw Attlog¶

Menu Fingerspot > Raw Attlog menampilkan data scan mentah. Menu ini hanya bisa diakses oleh Administrator.

Kolom yang Ditampilkan¶

Kegunaan¶

• Audit trail - melihat semua data scan asli dari mesin
• Debugging - cek jika ada data yang tidak ter-sync dengan benar
• Verifikasi - bandingkan data raw dengan data attendance

11. Menu Webhook Logs¶

Menu Fingerspot > Webhook Logs (atau via smart button Webhooks di form mesin) menampilkan semua data yang diterima via webhook. Menu ini hanya bisa diakses oleh Administrator.

Kolom yang Ditampilkan¶

Kegunaan¶

• Audit trail - bukti semua data yang masuk via webhook
• Debugging - cek jika data webhook tidak terproses dengan benar
• Monitoring - pastikan mesin mengirim data secara rutin

12. Menu Sync Logs¶

Menu Fingerspot > Sync Logs (atau via smart button Sync Logs di form mesin) mencatat setiap eksekusi sync. Menu ini hanya bisa diakses oleh Administrator.

Kolom yang Ditampilkan¶

Filter & Group By¶

Filter: - Has Errors - tampilkan hanya sync yang ada error - Today - sync hari ini

Group By: - Machine - kelompokkan per mesin - Triggered By - kelompokkan per pemicu (user/cron)

Kegunaan¶

• Monitoring - pantau apakah sync berjalan lancar setiap hari
• Troubleshooting - identifikasi sync yang gagal dan lihat detail error
• Audit - siapa dan kapan sync dijalankan

13. Koreksi Manual oleh Admin¶

Admin dapat mengedit data attendance untuk keperluan koreksi. Record yang sudah dikoreksi dilindungi dari overwrite oleh sync berikutnya.

Cara Koreksi¶

1. Masuk Fingerspot > Attendance
2. Buka record yang ingin dikoreksi
3. Edit field yang perlu diubah:
4. Check In - koreksi waktu masuk
5. Check Out - koreksi waktu pulang
6. Klik Save
7. Field Manually Corrected otomatis tercentang

Proteksi Koreksi Manual¶

• Saat admin mengedit Check In atau Check Out, field Manually Corrected otomatis aktif
• Record dengan Manually Corrected = True tidak akan di-overwrite oleh sync berikutnya
• Jika ingin record kembali mengikuti data dari mesin, uncheck Manually Corrected lalu jalankan sync ulang

Contoh Case¶

Yang Perlu Diperhatikan¶

• Setiap perubahan akan tercatat di log (lihat bagian Tracking)
• Hanya user dengan level Administrator yang bisa mengedit
• Perubahan pada Check In / Check Out akan otomatis menghitung ulang Total Hours
• Record yang dikoreksi aman dari overwrite sync

14. Cron Job (Auto Pull & Sync)¶

Modul ini menyediakan scheduled action yang otomatis menjalankan Pull dan Sync.

Konfigurasi Default¶

• Nama: Fingerspot: Pull & Sync Attendance
• Interval: 1x per hari
• Proses: Pull data raw dari semua mesin aktif, lalu sync ke attendance

Cara Mengubah Jadwal¶

1. Masuk Settings > Technical > Automation > Scheduled Actions
2. Cari "Fingerspot: Pull & Sync Attendance"
3. Ubah interval sesuai kebutuhan (misal: setiap 6 jam)
4. Klik Save

Catatan¶

• Cron berjalan untuk semua mesin aktif
• Cron hanya sync 2 hari terakhir (kemarin + hari ini) untuk performa optimal
• Untuk sync periode lebih panjang, gunakan wizard Sync Attendance secara manual
• Jika ada mesin yang gagal, error di-log dan mesin lainnya tetap diproses
• Setiap eksekusi cron tercatat di Sync Logs dengan triggered_by = "Cron"
• Cek log error di Settings > Technical > Logging atau di Fingerspot > Sync Logs

15. Tracking / Audit Log¶

Setiap perubahan pada data Attendance dicatat secara otomatis di bagian chatter (log di bawah form).

Field yang Di-track¶

Cara Melihat Log¶

1. Buka record Attendance
2. Scroll ke bawah form, lihat bagian Chatter / Log
3. Setiap perubahan tercatat dengan informasi:
4. Siapa yang mengubah (user)
5. Kapan diubah (tanggal & waktu)
6. Apa yang diubah (field lama → field baru)

16. Troubleshooting¶

"Connection to Fingerspot API timed out"¶

• Penyebab: Server Odoo tidak bisa terhubung ke API Fingerspot
• Solusi: Cek koneksi internet server. Pastikan URL API benar

"Fingerspot API error: 401"¶

• Penyebab: API Token tidak valid
• Solusi: Periksa kembali API Token di form mesin. Pastikan token masih aktif di akun Fingerspot developer

"Fingerspot API error: 404"¶

• Penyebab: Endpoint API tidak ditemukan
• Solusi: Pastikan API URL diisi dengan https://developer.fingerspot.io

Data attendance tidak muncul setelah Pull¶

• Penyebab 1: Data sudah di-pull tapi belum di-sync

• Solusi: Klik tombol Sync Attendance di form mesin

• Penyebab 2: PIN belum di-link ke employee

• Solusi: Sync hanya memproses PIN yang sudah ada employee-nya. Link PIN ke employee dulu, lalu sync ulang

Employee tidak ter-link di attendance¶

• Penyebab: Fingerspot PIN belum di-set di employee
• Solusi: Buka form employee > tab Fingerspot > isi PIN > Save. Jalankan sync ulang untuk memproses data raw yang sebelumnya di-skip

Check In = Check Out (Worked Hours 0:00)¶

• Penyebab: Hanya ada 1 scan di hari tersebut (misal hanya checkin atau hanya checkout)
• Solusi: Admin bisa koreksi manual Check In atau Check Out sesuai kondisi sebenarnya. Record akan otomatis dilindungi dari overwrite sync

Koreksi manual ter-overwrite oleh sync¶

• Penyebab: Field "Manually Corrected" tidak tercentang
• Solusi: Ini seharusnya tidak terjadi — field otomatis tercentang saat edit Check In/Check Out. Jika terjadi, centang manual field tersebut

Webhook 404 / data tidak masuk¶

• Penyebab 1: Webhook URL tidak bisa diakses dari internet

• Solusi: Pastikan server Odoo memiliki public URL atau gunakan reverse proxy

• Penyebab 2: Multi-database tanpa dbfilter

• Solusi: Tambahkan dbfilter = nama_database di odoo.conf, lalu restart Odoo

• Penyebab 3: URL webhook belum di-set di Fingerspot Cloud

• Solusi: Copy Webhook URL dari form mesin dan paste di dashboard Fingerspot

Cron tidak jalan¶

• Penyebab: Scheduled action tidak aktif atau Odoo cron worker tidak berjalan
• Solusi: Cek di Settings > Technical > Scheduled Actions, pastikan "Fingerspot: Pull & Sync Attendance" dalam status Active

Sync error pada beberapa record¶

• Penyebab: Data corrupt atau PIN tidak valid
• Solusi: Cek detail error di Sync Logs atau di wizard sync. Record yang gagal tidak ditandai synced dan bisa di-retry setelah masalah diperbaiki