Ask any HR manager in Saudi Arabia what a normal month looks like, and the answer rarely starts with "payroll." It starts with tabs: Muqeem for exit/re-entry visas and Iqama renewals, Qiwa for employment contracts, GOSI for registrations and wage changes, the bank or Mudad portal for the WPS salary file, and a spreadsheet that ties it all together. Then come the Saudi-specific payroll rules that standard HR software was never designed for: the new progressive GOSI pension rates, overtime paid on the full wage plus half of basic, leave rules where Fridays count in one case and not in another, and contract employees who move between project sites with different timings.
At ERPGulf we implement ERPNext for Saudi companies across manufacturing, retail, real estate and construction, and we kept meeting the same problems at every client. So we built them once, properly, into a single Frappe app that runs on top of Frappe HRMS: hrms_saudi.
This article walks through what it does, module by module: payroll and GOSI, overtime, attendance and leave, employee records and self service, and the newest part, Government Services, which brings Muqeem, Qiwa, GOSI and WPS work into the same system as the employee and the payroll. It is written for HR managers, finance teams and IT leads who want to understand exactly how it works before a demo.
What hrms_saudi is
hrms_saudi is an app for ERPNext version 16 with Frappe HRMS. It does not replace HRMS; it adds what Saudi companies need on top of it, and it is already running in production at several Saudi companies. Three design rules shape everything in it:
Standard HRMS stays standard. Salary Slips, Payroll Entries, Leave Applications and Overtime Slips are the normal HRMS documents. hrms_saudi adds fields, calculations and buttons; your team keeps working in screens it already knows, and future HRMS upgrades keep working.
Nothing changes until you switch it on. New calculation methods are new options; existing settings keep calculating exactly as before. The Government Services module is off by default for every company.
One app for every Saudi client. When we build a feature for one client, every other client on the app can use it. Improvements reach you through normal updates, and changes required by Saudi law are included at no extra fee.

Payroll and GOSI, done the Saudi way
GOSI on every Salary Slip
Each salary component has a GOSI Included tick. The GOSI base is the sum of the ticked earnings, capped at the maximum base (45,000 by default). hrms_saudi then calculates both shares on every Salary Slip:
For Saudis, the pension rate depends on the subscriber type. Existing subscribers stay on the existing rate (9% by default). New subscribers follow a progressive pension schedule, preloaded with 9.5% from July 2025 rising to 11% by July 2028, and picked by the slip's posting date. Every rate is editable in GOSI Setting, and a site's own edits are never overwritten by updates.
For example, a Saudi existing subscriber with a GOSI base of 10,000 SAR gets a deduction of 975 SAR (9% + 0.75% SANED) and an employer cost of 1,175 SAR (9% + 2% hazard + 0.75% SANED), calculated automatically and never duplicated, however many times the slip is saved.
One GOSI journal entry per payroll
When the last Salary Slip of a Payroll Entry is submitted, hrms_saudi posts one Journal Entry for the total employer GOSI: GOSI expense debited, GOSI payable credited. Accounts can differ by GOSI Employee Category (for example, project staff and head-office staff), with a company default as the fallback. Cancelling the payroll cancels the GOSI entry.
One detail saves many first payrolls: the GOSI payable account must be a Liability account with Account Type left empty, because ERPNext demands a party on every Payable account and GOSI owes on behalf of all employees together. hrms_saudi only offers suitable accounts in that field, and explains why in the documentation.
Payroll cost by project
For contracting companies, payroll cost has to land on projects. Check-ins carry a Project; each day's attendance takes the project with the most hours; and when a Payroll Entry has Include Project In Journal Entry ticked, the salary and GOSI journal entries are split by project in proportion to each employee's project days, with the rounding absorbed so every entry stays balanced.
Leave without pay that costs more than one day
Many Saudi companies deduct more than one day's pay for an unauthorised absence. Each LWP leave type gets a Number of Days of Deduction: set it to 2, and one unauthorised day reduces payment days by 2 (half a day by 1). It works whether payroll is based on leave or on attendance, and it reads HRMS's own rules for holidays and half days, so nothing else in the slip changes.
Overtime the Saudi way
Standard HRMS calculates overtime from one salary component or a fixed hourly rate. Saudi companies need more than that, so hrms_saudi adds three calculation methods to every Overtime Type:
Package + % of Basic
This is the method many Saudi companies apply under the Labour Law's overtime rule: the employee receives the normal hourly wage plus 50% of the basic hourly wage for each overtime hour. In hrms_saudi it is a setting, not custom code. You choose which components form the package (for example Basic, Housing and Transport), which form the basic, the premium percentage (50 by default), whether a day is the company's Monthly Payment Days or a twelfth of the year, and the hours per day.
A worked example, with Basic 2,400, Housing 1,600 and Transport 800 SAR, 30 days and 8 hours:
Weekend and public-holiday multipliers still apply on top, exactly as in HRMS, and a warning appears if a multiplier would pay the premium twice.
Contract hours instead of fixed shifts
Contracting and facility companies pay staff on contract hours (8 or 10 a day) while they move between sites with different timings. Instead of one shift per site, hrms_saudi uses one Contract Hours shift per contract length with a wide check-in window. When attendance is submitted, the app works out the day:
Worked hours = last check-out − first check-in − lunch break
Overtime = worked hours above the contract hours
Undertime = contract hours not worked
On a weekly off or holiday, every worked hour is overtime
Overtime flows into the normal Overtime Slip, and undertime appears on the Salary Slip as hours and days, ready for an undertime deduction formula in the salary structure.
Hundreds of slips in one go
The Bulk Overtime Slip Tool creates overtime slips for a whole company, branch or department for a period, in the background, skipping employees who already have a slip. HR reviews and submits them as usual, and the amounts reach payroll as Additional Salary.
Attendance and leave
Daily earned leave
In standard HRMS, earned leave is credited monthly or yearly. Many Saudi companies accrue annual leave every day: 30 days a year is about 0.082 days for every calendar day. With Earned Leave Frequency = Daily, hrms_saudi builds a day-by-day schedule on the Leave Allocation, credits completed days only (never today or the future), and adds one ledger entry per day through a nightly job. A leave type marked Is Deducted From Annual Leave Allocation (for example Personal Leave) removes those days from the schedule, and cancelling the leave gives them back.
Holidays and weekends inside leave
Whether a Friday or public holiday counts as leave depends on how the leave was applied. With the leave type set to include holidays, a weekend or holiday inside one leave application counts as leave; one before, after or between two separate applications stays paid. We document the common cases for clients (two separate applications around a Friday, a week-long application, leave next to Eid holidays) so HR teams can predict the payroll result before they approve.
Shift on leave days
When HRMS marks an approved leave as "On Leave" attendance, the shift is often left empty, which breaks shift-based reports. hrms_saudi fills it from the employee's active Shift Assignment for that date, and never overwrites a shift someone chose.
Imports and the Monthly Time Sheet
Employee Checkin import: one Excel row per employee per day (date, time in, time out, optional shift and project) becomes an IN and an OUT check-in. Unknown employees, missing values and duplicates are skipped, with the reasons listed.
Additional Salary import: one column per salary component; everything is checked first, and if one row is wrong, nothing is imported.
Monthly Time Sheet: per-employee monthly sheet with contract hours, lunch, worked hours, overtime, late entries and early exits in red, weekends and holidays filled in, and leave types by name.
Leave Ledger - Saudi and Employee Leave Balance - Saudi: the HRMS leave reports with Saudi additions such as an LWP column.
Employee records and self service
A Saudi employee profile
The Employee form gains the sections Saudi HR actually fills in: name in Arabic; Employment Profile with nationality, Iqama profession, National ID / Iqama number and expiry; GOSI Settings with employee type (Saudi or Expat), GOSI category and subscriber type; GOSI number and medical insurance class; driving licence; professional certifications; Family Details with dependents and their ID numbers; and Company Assets issued to the employee. Passport and bank details use the standard ERPNext fields, so nothing is stored twice.
The Salary Structure Assignment gains Housing (HRA), Transportation (TA) and Other Allowance fields, which salary formulas, the self-service page and Government Services all read from the same place.
Employee Self Service page
Employees get one page inside the system with their own record only:
APIs for mobile apps
Dependents can be read and changed through REST endpoints, ready for ERPGulf's employee mobile apps or any third-party app, with the same permissions as the Employee record.
Government Services: Muqeem, Qiwa, GOSI and WPS inside ERPNext
The newest part of hrms_saudi tackles the biggest daily time sink: work on government portals that lives outside the ERP. Today, HR prepares an exit/re-entry visa in Muqeem, a contract in Qiwa, a registration in GOSI and a salary file for the bank, then copies references back into spreadsheets. Government Services moves that work next to the employee and the payroll, with one record of what was requested, when, by whom and with which result.
[embedded content: how a government request travels · from the Employee screen to the updated record]
Every action starts from a Government menu on a screen HR already uses. The request is a proper document with its own approval: Submit approves it inside ERPNext, and only a separate Send step goes to the platform. Until a platform's API connection is in place for your company, HR completes the action on the government portal and records the portal's reference and PDF with Mark done manually. Either way, the Employee record is updated and the action appears in the employee's government history.
What each platform covers
A day in the life
An employee's annual leave is approved. HR opens the Leave Application and presses New Exit/Re-entry Request: the visa request opens with the employee, the travel dates and a link to the leave already filled in, and the Iqama and passport numbers fetched from the employee record. HR submits it and issues the visa on Muqeem, then records the visa number and the portal's PDF. From the departure date, the employee shows as Currently Abroad; when they return, Record return closes the trip. Months later, anyone can open the employee's Government history and see every visa, contract, GOSI change and salary payment in one list.
At month end, payroll is submitted as usual. Pressing Create WPS Batch on the Payroll Entry builds the salary file from the submitted salary slips; any employee with a missing or invalid IBAN is listed before anything leaves the system, so bank rejections stop being a surprise.
Settings per company, and only for Saudi companies
Each company has its own Government Services settings: a master switch, a switch per platform, its own credentials and its own connection status (Not connected, Sandbox or Production). Groups with companies in several countries can run them on one ERPNext site: the Government menu, the settings and the Employee's Government Services section appear only for companies whose country is Saudi Arabia. A company that has not switched the service on sees a clear message instead of a half-working feature.
Built for API connections
Every platform already has its screens, statuses, retries, audit log and Employee updates. Connecting a platform's API, when access is granted for a client, adds a connector behind the existing Send button; nothing changes for the users or their data. Until then, the manual route gives the same records, history and reports from day one.
Safe for a live payroll
HR software touches salaries, so how it is built matters as much as what it does. hrms_saudi follows a few rules we never bend:
Existing behaviour never changes silently. New calculation methods are new options. A client who never selects Package + % of Basic gets exactly the overtime they had before, down to the halala.
Government Services never runs on Save or Submit. Saving an Employee or submitting a payroll does exactly what it did before. Government actions run only when someone presses a Government button, after checking the company, the user's role and the switches.
Clear roles. Gov Integration Manager controls settings and connections; Gov Integration User handles day-to-day requests. A completed government action cannot be cancelled in ERPNext until it has been cancelled on the platform, so records and reality never drift apart.
A full audit trail. Every platform call and every manual completion is logged with the user, time, document and result. Passwords, tokens and keys are masked, and IBANs show only their last four digits. Logs are kept for a period each company chooses (180 days by default).
Problems are caught before they leave. A WPS batch with a missing or invalid IBAN, or a zero net pay, cannot be submitted; every failing line is listed at once. A visa request for an employee without an Iqama number is stopped on save.
Robust background work. Sending happens in the background; temporary platform outages are retried automatically after 5, 15 and 30 minutes, while real validation errors are shown to the user instead of being retried.
Works without optional apps. A site does not need ERPNext's lending app or any other extra app for hrms_saudi to install and run; features that depend on one switch on only where it exists.
What is coming next
Government Services is being built in steps. Here is where it stands and what comes next:
As with every ERPGulf app, clients receive these as normal updates.
Why ERPGulf
ERPGulf implements ERPNext across Saudi Arabia, and many other ERPNext partners in the Gulf rely on our apps, including our ZATCA e-invoicing app. With every implementation, we commit to:
100% code transfer and full administrator access for your own staff.
Freedom to move: your system can go to your own cloud or on-premise at any time.
Saudi law changes at no extra fee: when GOSI rates, labour rules or government requirements change, the update is ours to deliver.
Transparent policies, on-site support and training when you need it.
Screens, reports and dashboards designed the way your HR and finance teams work.
Frequently asked questions
Do we have to replace Frappe HRMS? No. hrms_saudi runs on top of HRMS on ERPNext version 16. Your team keeps the standard Salary Slip, Payroll Entry, Leave Application and Overtime Slip screens.
Will installing it change our current payroll? No. New overtime methods and Government Services are opt-in. Existing settings calculate exactly as before until you choose otherwise.
Does Government Services connect directly to Muqeem, Qiwa and GOSI today? Every platform is ready for its API connection, which is added per platform as access is granted. Until then, HR completes the action on the portal and records the reference with Mark done manually, so the records, Employee updates and history are complete from day one.
We have companies outside Saudi Arabia on the same system. Is that a problem? No. Government features appear only for companies whose country is Saudi Arabia, and each Saudi company has its own settings and switches.
How is overtime "full wage plus 50% of basic" configured? With the Package + % of Basic method on an Overtime Type: choose the package components, the basic components and the premium percentage. No custom code is needed.
Can employees see their own data? Yes, through the Employee Self Service page: profile, salary, bank details, dependents, photo, leave balance and leave requests. They see only their own record.
See it on your own data
The best way to judge hrms_saudi is to watch it run your scenarios: your GOSI mix, your overtime policy, your leave rules and your government workflows. Book a meeting with our team and we will walk you through it.
Website: www.erpgulf.com
Email: sales@erpgulf.com
Phone and WhatsApp: +966 53 546 9548

