AI AI Workforce OS v1.0.0

Payroll

Payroll periods and runs, payslips, adjustments, and payroll reports.

HR AdministratorsPayroll AdministratorsEmployees (view only)

Overview#

Payroll manages payroll periods and runs, computes gross and net pay from configured pay components, applies adjustments, and generates payslips.

Purpose#

Explain what payroll processing covers today, what employees can see about their own pay, and an important limitation on tax calculation and the run-execution UI.

Prerequisites#

  • Compensation packages assigned to employees (see Compensation, configured under Performance/Compensation setup).
  • A defined payroll period.

Step-by-Step Instructions#

Viewing your pay (employee)#

  1. Open Payroll in ESS.
  2. Review your payslip history and salary breakdown for each period.
  3. This view is read-only — contact HR/Payroll for corrections.

Payroll periods and runs (payroll administrator, via API)#

  1. Create a payroll period.
  2. Create a payroll run for that period and generate a preview.
  3. Submit the run for approval, then approve or reject it.
  4. Finalize and lock the run once approved. Locking prevents further edits.
  5. Generate payslips from the finalized run.
⚠
No web UI to execute a payroll run in this release

The steps above exist as API operations. The HR Admin web screen for Payroll is currently read-only — it lists periods and runs but does not expose buttons to create, preview, submit, approve, finalize, or lock a run. Confirm with your implementation team how payroll runs are actually being executed for your tenant (for example, via direct API calls or a script) until a web UI ships.

Adjustments and reports#

  1. Create a payroll adjustment for a specific employee/period, and route it for approval.
  2. Run cost-attribution and disbursement reports once a period is processed.

Screens Involved#

📷
[Screenshot: ESS Payroll (payslip history, salary breakdown)]
📷
[Screenshot: MSS Payroll summary (view only)]
📷
[Screenshot: HR Admin Payroll (periods/runs, read-only)]

Expected Results#

Employees can view accurate, up-to-date payslips once a run is finalized. Administrators can track adjustments and pull cost and disbursement reports.

Not Available in This Release#

🚫
Not currently available
  • No automated income tax, provident fund, or other statutory/country-specific deduction calculation. The calculation engine defines a plugin interface for this, but no plugin ships or is registered in this release — only the pay components an administrator manually configures are calculated.
  • No web UI to execute a payroll run end-to-end (create → preview → submit → approve → finalize → lock) — the HR Admin Payroll screen is read-only. The underlying API supports the full lifecycle.

Common Mistakes#

  • Assuming the system calculates statutory tax/PF/ESI deductions automatically — it does not, unless your organization has built and registered a custom tax plugin.
  • Looking for a "Run Payroll" button in HR Admin and not finding one — this is expected in the current release.
  • Editing a locked payroll run instead of creating an adjustment.

Troubleshooting#

A payslip has the wrong net pay.#

Verify the employee’s assigned compensation package and pay components first, then check for any unpaid-absence or leave-without-pay proration applied for that period. Remember that statutory tax deductions are not calculated automatically in this release — if your organization needs them reflected, they must be entered as manually configured pay components.

I need to fix a finalized, locked payroll run.#

Locked runs are not editable directly. Use a payroll adjustment for the affected employee and period instead, and route it through approval.

AttendanceLeaveHR Admin

FAQ#

Does the system calculate my income tax automatically?

No. There is no statutory tax/PF/ESI calculation engine active in this release. Only manually configured pay components (earnings and deductions) are calculated into gross and net pay.

Can I run payroll from the web app?

Not fully, today. The HR Admin Payroll screen is read-only. The payroll-run lifecycle exists at the API level; ask your implementation team how runs are being executed for your organization.

Why does my payslip reflect a deduction for unpaid leave?

Payroll calculation prorates pay for recorded unpaid absence or leave-without-pay against your attendance and leave records for the period.

Best Practices#

  • Reconcile attendance and leave for a period before finalizing the payroll run for that period.
  • Track any statutory deduction requirements separately until a tax plugin is available, so payslips remain auditable.