Payroll Module — User Guide

1. Overview

The Payroll module calculates and manages monthly employee pay. It combines:

Payroll does not replace HR master data. Employees, org structure, and career events live in HR. Attendance punches live in Attendance. Payroll consumes an active salary and configured rules to produce a payslip for a date range.

2. Getting started

2.1 Recommended setup order

1. Calculation parameters — reusable numeric/formula knobs
2. Formula variables — named bridges used inside formulas and built-in tax/advance totals
3. Employee groups — optional targeting lists
4. Dynamic rules — compensations, grants, deductions
5. Advance types — categories for advances
6. Salaries — one active salary per employee before any payslip
7. Operational data: advances, additional deductions, monthly changes
8. Generate payslips → review → Execute to lock

Payslips are generated per employee for a period (no dedicated batch API; the UI may loop employees).

2.2 Main navigation

3. Calculation parameters

Reusable named values that formulas and rules can reference.

Dynamic rules can reference parameters via parameter references. At runtime the engine resolves the current value for the employee/period context.

4. Formula variables

Named variables that connect payroll screens and SQL-backed calculations.

Common built-in uses during payslip calculation include tax-related variables and totals such as:

• Grant / bracket / income tax variables
• Total advance installments for the month
• Total additional deductions for the month

You can evaluate a variable or a formula from the admin APIs/UI when configuring rules.

5. Employee groups

Groups collect employees for organization and (intended) rule targeting.

5.1 Group

5.2 Members

Manual membership: employee, active flag, optional expiry, notes. Bulk add can attach many employees and skip duplicates.

5.3 Criteria

Criteria rows describe filters (department, location, specialization, status, custom) with operators such as =, IN, LIKE, comparisons, and null checks.

Practical note: Membership used in day-to-day pay is the manual member list. Criteria are maintained as configuration metadata. For payslip calculation, dynamic rules that apply reliably today are those targeted to All or Individual employees; group-targeted rules may not be applied by the calculation engine until group expansion is fully wired.

6. Dynamic rules

Dynamic rules add compensations, grants, or deductions to a payslip when they match an employee and effective dates.

6.1 Rule types

6.2 How the amount is calculated

Calculation sources include Gross, Net, Fixed, Other, Compensation, Grant. Percentage resolution currently anchors to fixed salary for several of these sources.

6.3 Targeting and schedule

Suspend / Resume actions temporarily stop a rule without deleting it.

6.4 When rules run in a payslip

Each applied rule can be recorded as a rule application for audit on that payslip month.

7. Salaries

Every payslip requires an active salary for the employee.

Rules

• Creating or activating a salary deactivates the previous active one.
• Payslip generation fails if no active salary exists.
• History is available via salary history APIs/UI.

There is no direct job-grade link inside Payroll; grade changes in HR do not automatically rewrite salary — maintain salary records explicitly (or via your operational process).

8. Advance types, advances, and installments

8.1 Advance types

Simple named categories (for example housing, salary advance). Manage under Advance Types.

8.2 Advances

Create paths:

Suspend / Resume control whether the advance participates in installment generation. You cannot delete an advance that already has paid installments (unpaid installments may be cleared first per rules).

8.3 Installments

Installments are the monthly repayment rows linked to an advance.

Auto-creation happens when generating/calculating a payslip month (or via calculate-installments-for-month), if:

• Advance is deducted, not suspended, remaining amount greater than 0
• No installment yet for that advance/employee/month/year
• Installment amount is positive and remaining covers it

Then remaining amount is recalculated from total minus all installment amounts.

In the payslip: unpaid installments for the period feed total advance installments into total deductions. Mark as paid excludes them from future unpaid totals.

9. Additional deductions

Recurring deductions such as loans or other withholdings.

Month flow

You cannot delete a deduction that already has paid amount greater than zero. Suspend / Resume stop or resume monthly pickup.

10. Monthly changes

Monthly changes record period adjustments for an employee (reason text, from/to dates, decision fields).

Execute locks the record. In the current product, monthly changes are primarily documentary / reportable; they do not automatically rewrite salary or payslip totals. Use them for controlled period notes and reporting, and adjust salaries or dynamic rules when amounts must change.

11. Payslips

11.1 Lifecycle

There is no separate Draft status enum. Practically:

11.2 Calculation outline

1. Validate employee, period uniqueness, payslip number, active salary.
2. Ensure advance installments and additional deduction payments for the month.
3. Work days from the calendar span of From–To; daily rate typically fixed salary / 30.
4. Apply compensation and grant rules → refresh gross.
5. Calculate taxes via formula variables; round income tax as configured.
6. Apply deduction rules.
7. Add advance installment and additional deduction totals.
8. Compute total deductions, salary before tax, net, and rounded net.

11.3 Payslip content

Header totals typically include: payslip number, period, assigned/actual work days, daily salary, gross, compensations, grants, deductions, tax fields, net, decision metadata, executed flag.

Payslip detail screen loads the slip plus related salary/advances/installments for review and save-all editing when not locked.

12. Reports and related HR data

Payroll exposes report APIs for complete payslip details, compensations/grants, dynamic deductions, additional deductions, monthly changes, and rewards/penalties sourced from HR data via reporting queries.

HR module reports (monthly payslips, payslip full details) also surface payroll outputs for HR users with the matching HR report permissions.

There is no dedicated Payroll dashboard menu; use Payslips and report consumers for operational oversight.

13. Employee portal

Under the HR employee portal, employees can open:

Portal access is gated by HR portal policies plus Payroll advance permissions such as Request and ViewOwn.

14. Permissions summary

Permission group: Payroll.

Grant Create/Execute-path payslip rights only to payroll operators; grant Request/ViewOwn to employee roles for portal self-service.

15. Integration with HR and Attendance

Appendix A — Quick procedures

A.1 Prepare payroll for a new employee

1. Ensure the person/employee exists in HR.
2. Create an active salary.
3. Attach any individual dynamic rules if needed.
4. Optionally register advances or additional deductions.
5. Generate the first payslip for the period.

A.2 Close a payroll month for one employee

1. Confirm salary, rules, advances, and deductions are up to date.
2. Generate or open the payslip.
3. Review totals on Payslip detail; Recalculate if configuration changed.
4. Execute to lock.
5. Use reports for distribution/audit.

A.3 Run an advance through payroll

1. Create advance type if needed.
2. Create advance with total and installment amount; keep Deducted on.
3. Generate payslip for the month → installment auto-created if eligible.
4. After collection, Mark installment paid when appropriate.

A.4 Configure a new allowance

1. Optionally add calculation parameters / formula variables.
2. Create a Dynamic rule of type Compensation or Grant.
3. Target All or Individual, set priority and effective dates.
4. Generate a test payslip and verify rule applications.
5. Execute production payslips when verified.

Appendix B — Operating notes

Appendix C — Document control

This guide describes functional capabilities of the Payroll module as implemented in the Vertex ERP codebase. UI labels may appear in English or Arabic depending on language settings.