Face Recognition Attendance for ERPNext

ECOSIRE Face Attendance adds a face-verification step before creating a native Employee Checkin. Employees use Face Check-in on their own phones; a shared tablet uses Attendance Kiosk. ERPNext's shift, attendance, and payroll processes continue to use their existing records.

This guide covers app 0.2.2 on Frappe/ERPNext v16 with HRMS. Confirm the installed release and your agreed installation scope with your administrator. A source repository, an active licence, and an available download are separate parts of delivery.

Before you start

Your administrator needs an installed app, a working HTTPS site, HRMS, and permission to configure Face Attendance. Each employee needs an active Employee record in the correct company. Mobile check-in also needs a linked user account and an active face enrollment.

Use a supported browser with camera permission and suitable lighting. Test the actual phone or tablet that employees will use. Face matching depends on camera quality, enrollment quality, and configuration; the configured confidence threshold is not a measured accuracy guarantee.

Administrator setup

1. Open Face Attendance Settings. Confirm that the app is enabled, download the configured face models, and run the engine self-test.
2. Confirm that the app's assets are built and reachable. A page returning HTTP 200 is insufficient if its JavaScript or styles fail to load.
3. Check Employee-to-user links, company assignments, and the roles needed for enrollment and attendance review.
4. Create the required Face Attendance Location records and configure geofence and shift-window behaviour for your rollout.
5. Enroll a small pilot group and verify an accepted check-in against the resulting Employee Checkin before extending access.

The app stores face embeddings and enrollment history in your ERPNext site. Enrollment records include consent; an enrollment cannot become active without it. Set an appropriate retention policy and explain the biometric process to staff before enrollment.

Installation checklist for a bench administrator

Use the approved release from your ECOSIRE delivery or repository access. The maintained source is ecosire/ecosire_face_attendance. Do not substitute an older repository or branch based only on a similar name.

After installation, download the verified model files and build the app's assets. The documented administrator commands are:

bench --site <site> install-app ecosire_face_attendance
bench --site <site> execute ecosire_face_attendance.face.model_store.download_models
bench build --app ecosire_face_attendance

Replace the site placeholder with the intended site. Follow your release's upgrade instructions and backup procedure; do not run installation or configuration commands against an unintended tenant.

Employee enrollment and mobile check-in

HR can enroll an employee from Face Enrollment. Employee self-enrollment is available only when an administrator enables it.

1. Sign in with the account linked to your Employee record.
2. Open Face Check-in from the Face Attendance workspace or visit /face-checkin on your ERPNext site.
3. Allow the browser to use the camera. Follow the requested action and keep one face in view.
4. Read the result. Accepted creates an Employee Checkin; Pending Review needs HR review; Rejected does not become an accepted attendance record.

On Android, use Add to Home Screen when the browser offers installation. On iPhone, use the browser's Share menu to add the page to the Home Screen. Face Check-in is its own app; it does not add a tile to Frappe HR's mobile home screen.

Shared tablet kiosk

An administrator creates a Kiosk Device, assigns its company and location, and issues its device token. Open /face-kiosk and pair that tablet with the device name and token. Treat the token as a credential: do not put it in shared screenshots, support messages, or printed instructions.

A kiosk identifies employees within the device's company. Verify both an allowed employee and an employee outside that company during commissioning. Test token expiry and unpairing before putting the device into daily use.

Offline capture and review

A paired kiosk can reserve challenges while connected, then queue captures during an outage. Offline captures are marked for review according to Face Attendance Settings → Offline Captures. Knowing a challenge in advance provides weaker liveness assurance than a newly issued online challenge.

The local queue is bounded to 200 captures and seven days. Unpairing erases the device's queued captures and reserved challenges. Reconnection is not proof of successful attendance: inspect the sync result and the associated Face Checkin Log. Repeated submission uses the capture identifier to avoid duplicate check-ins.

Liveness and attendance policy

The app uses heuristic checks for motion, the requested action, a consistent single face, and image texture. It is not a certified presentation-attack detection system and does not provide a guarantee against high-quality masks or real-time deepfakes.

Texture enforcement can score or reject suspicious captures, depending on configuration. Test thresholds on the deployed hardware and establish a manual review process for borderline results.

Require Face Verification for App Check-in is optional and off by default. When enabled, it can require a recent face verification before ordinary app check-ins. HR and designated managers retain correction paths, and employees without active enrollment are exempt. Account for those exceptions in your attendance policy.

Troubleshooting

What you see	What to check
Camera does not open	HTTPS, browser camera permission, another app using the camera, and the device's browser support.
Employee cannot sign in	The user is linked to the correct Employee record and retains the Employee role.
No active enrollment	Recorded consent, enrollment status, quality, and the Employee's company.
Check-in needs review or is rejected	The Face Checkin Log outcome, lighting, face quality, location, shift rules, and configured thresholds.
Page says the app is switched off when it is enabled, or shows unresolved template text	Confirm release 0.2.2 or later and ask the administrator to check page-controller loading. That release repairs the controller filenames used by the check-in and kiosk pages.
Page opens but buttons or styles fail	Confirm that the app assets were built and that their requests succeed.
Offline capture is absent from attendance	Inspect the queue and sync outcome; check challenge validity, age, review status, and whether the device was unpaired.

For help, contact ECOSIRE support with the app version, ERPNext/Frappe version, affected page, and a redacted error description. Do not include device tokens, passwords, face captures, or employee biometric templates.