Detailed Functional Requirements
Employee Payroll Profile — Detailed Requirements
What must be true of an employee before they can be paid correctly: the payroll-relevant attributes on the employee master (tax profile, nationality, birth date, employment dates, contribution group), the standing item assignments that define what they earn and what is deducted, and their per-scheme statutory registration numbers. The pay run never edits this data — it reads it.
3
Data sources
7
Requirements
1
Import flow
Payroll profile
Tax residency, tax category, children, nationality, birth date, join/resign dates, contribution group.
Item assignments
Catalogue items assigned with an amount and an effective date window — the source of truth for what gets paid.
Statutory numbers
The employee's EPF / SOCSO / income-tax numbers for payslips and annual forms.
Employee · Detailed
Data model
Payroll reads the HR employee master and owns two satellites: the standing item assignment and the per-scheme statutory number.
Employee (HR master)
payroll-relevant fields| Field | Type | Notes |
|---|---|---|
basicSalary | number | Fallback base; the run prefers the basic-salary item assignment when present. |
taxResidencyStatus key | enum | RESIDENT (default) / NON_RESIDENT — selects the PCB method. |
taxCategory key | enum | SINGLE / MARRIED_SPOUSE_WORKING / MARRIED_SPOUSE_NOT_WORKING — drives spouse relief. |
numberOfChildren | number (default 0) | × per-child relief. |
annualPersonalRelief | number (default 0) | Manual additive relief top-up per employee. |
nationality key | string | Drives foreign-worker EPF; blank/unknown treated as Malaysian. |
dateOfBirth key | date | Age at pay date → EPF senior rates, SOCSO category, EIS eligibility. |
employmentType | enum | FULL_TIME / PART_TIME / CONTRACT / INTERN / DOMESTIC_SERVANT — domestic servants are excluded from foreign-worker EPF. |
joinDate, resignDate key | dates | Drive mid-month proration and Borang E new/ceased counts. |
payrollContributionGroupId key | reference | The statutory policy applied when joining a run. |
attendanceGroupId | reference | Shift schedule → working-day set, working days/month, hours/day (defaults Mon–Fri, 30 days, 8 h). |
EmployeePayrollItem
standing assignment| Field | Type | Notes |
|---|---|---|
employeeId | reference | Required. |
itemSettingId | reference → catalogue | The item definition supplying all behaviour flags. |
amount | number (default 0) | Flat amount for this employee — no formulas or percentages on the assignment. |
status | enum | ACTIVE (default) / INACTIVE. |
startDate key | date | Required. Effective from. |
endDate | date | Effective until; open-ended when unset. |
EmployeeStatutory
registration numbers| Field | Type | Notes |
|---|---|---|
employeeId + statutoryTypeId key | references | Unique per company + employee + scheme. |
number | string | EPF / SOCSO / income-tax number; used on the EA form and CP8D rows. |
Employee · Detailed
Payroll profile EMP-P
The employee master carries the attributes that parameterise every statutory and tax computation.
FR-EMP-P01Must
The system SHALL hold, per employee, the tax residency status, tax category, number of children, an optional manual annual relief top-up, nationality, date of birth, employment type, join/resign dates, and a contribution-group assignment — and payroll SHALL read these without modifying them.
Acceptance criteria
- Changing the tax category or children count changes the next calculated run's PCB (spouse relief only for married-spouse-not-working).
- An employee with no contribution group produces no statutory contributions.
- Age- and nationality-dependent statutory rules evaluate against date of birth and nationality at the run's pay date.
FR-EMP-P02Should
Rate derivation SHALL come from the employee's attendance group: the working-day set (shift weekdays minus company holidays) for daily rates, and working-days-per-month / hours-per-day for the overtime hourly rate — defaulting to Monday–Friday, 30 days and 8 hours when no group is assigned.
Acceptance criteria
- Daily rate = salary ÷ working days in the pay period.
- Hourly rate = salary ÷ working days per month ÷ working hours per day.
- Salary is always treated as a monthly amount — there is no daily/hourly-rated employee type.
Employee · Detailed
Item assignments EMP-A
The standing assignment of a catalogue item to an employee — amount plus effective window. These are what a pay run actually reads.
FR-EMP-A01Must
The system SHALL allow staff to assign catalogue items to employees with an amount, an active/inactive status, a required start date and an optional end date; an assignment is active for a run when its status is active and the run's pay date falls inside
[startDate, endDate] (open-ended when no end date).Acceptance criteria
- Assignments outside their window are ignored by the run without being deleted.
- Ending a recurring allowance mid-year only requires setting its end date.
FR-EMP-A02Must
An employee SHALL NOT hold two overlapping active assignments of the same catalogue item.
Acceptance criteria
- Create and import reject a new assignment whose window overlaps an existing active assignment of the same item (open-ended treated as infinite).
FR-EMP-A03Must
At read time the assignment amount SHALL be frequency-adjusted from its catalogue definition: annual items are smoothed ÷12 — unless flagged additional remuneration, which always pays the full lump sum.
Acceptance criteria
- A RM12,000 annual allowance contributes RM1,000 per month.
- A RM6,000 annual bonus flagged additional remuneration pays RM6,000 in the run where it is active.
- One-off items pay as-is; their single-month date window is what makes them pay once.
Employee · Detailed
Statutory numbers EMP-S
The employee's own registration numbers with each agency, mirroring the company-level store at employee scope.
FR-EMP-S01Must
The system SHALL hold at most one registration number per statutory scheme per employee, upserted through a per-employee form listing every scheme, and SHALL surface the EPF, SOCSO and income-tax numbers on the EA form and CP8D listing.
Acceptance criteria
- Upserting a blank number deletes the record.
- Missing numbers render blank on the forms — they do not block generation.
Employee · Detailed
Bulk import EMP-M
Item assignments can be loaded from a spreadsheet — the practical path when onboarding a whole workforce.
FR-EMP-M01Should
The assignment import SHALL resolve each row's employee by reference or PIN, the item by name, and optionally a contribution group by name (updating the employee's group link); it SHALL validate amount, start date, end ≥ start, and the no-overlap rule, previewing per-row errors before confirmation.
Acceptance criteria
- Unresolvable employee/item/group, missing amount, or invalid dates produce row-level errors and leave the row unpersisted.
- Confirmation re-validates, creates assignments, applies group updates, and reports success/error counts.
Employee · Detailed
Business rules
- Assignments are the source of truth for pay. The employee's
basicSalaryfield is only a fallback when no basic-salary item assignment exists. - Safe statutory defaults: blank nationality → Malaysian; missing birth date → under 60 and EIS-eligible.
- Join date on the 1st is a full month — proration triggers only for joins after the 1st or resignations within the pay month.
- Statutory numbers are identity data, not eligibility data — eligibility derives from age/nationality/employment type, never from the presence of a number.
Employee · Detailed
Known gaps
No bank / disbursement details. Neither the employee master nor the payroll line holds bank account or payment-method fields; payment is modelled only as a GL credit to a salary-liability account. No bank payment file can be produced.
No salary rate types. All salaries are monthly; part-time/hourly compensation must be approximated through items and the attendance-group derived rates.
Foreigner classification is label-based. Nationality is matched against a fixed list of Malaysian labels; a mistyped nationality can silently push a Malaysian onto foreign-worker EPF rates (a warning is logged).