Prerequisites & Installation
Prerequisites
Before you install this app, ensure the following are in place.
On the Frappe/ERPNext Side
| Requirement | Notes |
|---|---|
| Frappe Framework | The app targets Frappe 15.x (Python ≥ 3.10) |
| Frappe HR (hrms) | Must be installed and configured with at least one company |
| ERPNext | Recommended but not strictly required if using Frappe HR standalone |
| Working bench | Standard Frappe bench setup |
| Employee records | Employees must exist in Frappe HR before syncing; the app maps by employee ID |
| Shift Types | Shifts must be configured in Frappe HR for auto-attendance to work downstream |
On the BioStar Side
| Requirement | Notes |
|---|---|
| BioStar 2 server | Must be reachable over HTTPS from the Frappe server |
| TA (Time & Attendance) module | The API endpoints used are from the BioStar 2 TA module specifically |
| Admin credentials | An account with permission to call the TA API |
| Shifts configured | Employees in BioStar must have shifts/schedules assigned — this is what generates the check-in logs the API returns |
| Network access | The Frappe server must be able to reach the BioStar TA URL on the relevant port |
Critical: If BioStar employees do not have shifts assigned, the attendance report endpoint returns empty data even if the devices are recording punches. Shift setup in BioStar is a prerequisite, not an optional step.
Installation
Step 1: Clone the App into Your Bench
From within your bench directory:
bench get-app https://github.com/navariltd/navari-frappehr-biostar.git
If you want to pin to a specific release branch:
bench get-app --branch develop https://github.com/navariltd/navari-frappehr-biostar.git
Step 2: Install onto Your Site
bench --site [your-site-name] install-app navari_frappehr_biostar
Replace [your-site-name] with your actual site name, e.g. erp.mycompany.com.
Step 3: Run Migrations
bench --site [your-site-name] migrate
This creates the Biometric Settings doctype table in your database.
Step 4: Restart Bench
bench restart
Or in production:
sudo supervisorctl restart all
Step 5: Verify Installation
In your Frappe desk, go to Search and type "Biometric Settings". If the doctype appears, the app is installed correctly.
Frappe Cloud Installation
If you are on Frappe Cloud:
- Navigate to your site's dashboard
- Go to Apps → Install App
- Search for Navari Biostar or enter the GitHub URL directly
- Follow the prompts to install
Biostar Server Setup
The app depends on Biostar being properly configured to generate attendance logs. This is a one-time setup on the Biostar admin side.
Assign Schedules to Employees
In BioStar 2 TA:
- Go to Time & Attendance > User
- Select the employee
- Assign a Schedule (which references a Schedule Template and Shift)
Without this assignment, the attendance report API returns no records for that employee.
Create Shift Types and Schedule Templates
- Go to Time & Attendance > Schedule Template
- Create or verify shift templates that cover your working hours
- Create a Schedule that links these templates to a date range
- Assign the schedule to all relevant employees
A useful walkthrough of this process is available in Suprema's documentation and this video summary.
Verify Checkin Logs Are Being Created
Before connecting Frappe, verify that BioStar is generating check-in/check-out logs:
- Go to Time & Attendance → Report
- Select a date range and run the report
- If records appear, the API will return data for that same range
If no records appear in the BioStar UI, the API will also return nothing — fix the device/shift configuration before proceeding.
API User Account
The account used in Biometric Settings must have:
- Login access to the BioStar 2 TA portal
- Permission to access the Attendance Report API endpoint
- A stable password (avoid rotating this without updating Biometric Settings)