Human Resources (HR) Module — User Guide

1. Overview

The HR module is the people and employment core of Vertex ERP. It manages:

HR does not own payroll calculation or raw attendance punches. Those live in the Payroll and Attendance modules; HR stores the employment facts those modules consume, and the employee portal embeds selected Attendance/Payroll screens.

2. Getting started

2.1 Recommended setup order

Before day-to-day HR work, configure master data in this order:

1. Lookups — nationalities, religions, marital statuses, employment types, leave types, penalty/reward types, institutions, exit reasons, unions, academic degrees, job grades, positions, department types, benefit plans, insurance companies, contact/relationship types.
2. Departments — build the org tree.
3. Holidays & weekend days — needed for accurate leave day counting.
4. Leave entitlement / deduction rules — if leave balances or pay impact depend on rules.
5. Checklist templates — onboarding and offboarding item lists.
6. Training courses — if you will enroll employees in training.
7. Employees — create or receive from Recruitment, then assign to departments/positions.

2.2 Main navigation (admin)

2.3 Employee detail file

Opening an employee (/hr/employees/:id) shows tabs for the full HR file:

3. Reference data (lookups)

Lookups are shared lists used when creating employees and HR transactions. Maintain them under Lookups (and related dedicated screens).

3.1 Lists managed in Lookups

3.2 Related configuration screens

Leave type highlights: max days per year/request/service, carry-over, paid/unpaid, requires approval, affects promotion, religion-based, once-in-service, per-event, and Affected by holidays (exclude weekends/official holidays from day count).

4. Organizational structure

4.1 Departments

• Hierarchical (Parent → child).
• Typed via Department type.
• UI supports viewing the tree, adding unassigned employees, and seeing the derived department manager.

4.2 Positions and job grades

• Position: name, code, optional job grade, description, managerial flag, active flag.
• Job grade: code, name, salary band (min/max base), max promotions, sort order — used for career progression. An employee’s current grade is driven by grade-change / promotion history, not a single editable field alone.

4.3 Assignments

An assignment places an employee in a department with a position and employment type for a date range.

5. Employee master records

5.1 Person vs Employee

Relationship: one Person ↔ one Employee.

5.2 Employment status

Status changes are controlled by lifecycle rules (unless Override lifecycle permission is used). Changes are recorded in employee history.

5.3 Creating an employee

Required typically: personal identity fields, employee ID number, hire date; optional social insurance number and initial job grade.

On create, the system typically:

1. Creates Person + Employee (default status Active).
2. Optionally records an initial grade change.
3. Creates a login (Identity) user.
4. Starts the hire lifecycle → onboarding checklist (if templates exist).

Employees can also be created via Recruitment when a job offer is accepted (person, employee, assignment, qualifications, and documents transferred).

5.4 Soft delete and restore

Deleting an employee generally requires a confirmed exit (or lifecycle override). Soft-deleted persons/employees can be listed and restored according to application rules.

6. Assignments and transfers

6.1 Create assignment

1. Open employee → Assignments, or use Assignments / Departments.
2. Select department, position, employment type, start date.
3. Optionally mark Is manager (validated: one open manager per department).
4. Save.

6.2 Transfer

Transfer closes the current open assignment (end date = day before effective date) and opens a new one. Requires transfer/edit permission. History is written.

Alternatively, submit a change request of kind Transfer for approval (see §8).

7. Employee lifecycle (hire, status, exit)

7.1 Hire / onboarding

7.2 Status change

HR can change status directly (permission Change status) or via a Status change request. Allowed transitions follow lifecycle policy (e.g. Active ↔ Probation ↔ Suspended ↔ Terminated), with an override path for privileged users.

7.3 Exit (offboarding)

Employee exit statuses: Draft → Confirmed or Cancelled.

Typical fields: exit date, exit reason, decision number, last working day, notes, linked checklist.

Rules of thumb:

• Confirming exit requires required checklist items completed (unless override).
• Confirmed exit sets employment status to Terminated.
• Soft-delete of the employee record is gated on a confirmed exit (or override).

7.4 Checklists

Statuses: Open → Completed / Cancelled. Items can be marked done; whole checklist can be completed when requirements are met.

8. Change requests

HR change requests provide an approval layer for sensitive moves.

Request statuses: Pending → Approved / Rejected / Cancelled.

Permissions: create, view, approve under HR Change Requests.

9. Leaves, balances, and holidays

9.1 Concepts

9.2 Leave request statuses

Pending → Approved / Rejected / Cancelled.

9.3 Request and approval flow

9.4 Holidays screen

• Weekend days: which weekdays are non-working (e.g. Friday/Saturday).
• Official holidays: name, date range, type (official / religious / national / other), optional yearly recurrence.

10. Career events (promotions, grades, rewards, penalties)

10.1 Manual promotions

Record from-grade → to-grade with effective date, decision number/date, notes. Written to history. Permission group: Promotions.

10.2 Periodic promotions

Automated eligibility calculation for periodic grade progression:

• Target working-day threshold and percentage rules are applied in the module (e.g. required working days and a base percentage scaled by effective days).
• Unpaid leave beyond a configured threshold can reduce effective days.
• If a grade’s max promotions is exceeded, the engine may propose the next grade by sort order.
• Apply creates real Promotion records and typically requires an active Payroll salary.

10.3 Grade (category) changes

Direct grade assignment with decision metadata — visible on the employee Category changes tab. Distinct from a full promotion workflow when you need to set grade without the promotion path.

10.4 Penalties

Penalty type, decision date/number, effective month, amount, reason, issuer, execution flag (IsExecuted). Feeds disciplinary history and can interact with payroll reporting.

10.5 Rewards

Same shape as penalties, with disbursement flag (IsDisbursed) instead of execution.

11. Benefits and insurance

• Benefit plans (lookup): code, name, type (Health insurance / Other), link to insurance company.
• Employee benefits: plan, policy number, start/end, notes — managed on the employee Insurance tab.

Permissions appear under Health Insurances for view/create/edit/delete of enrollments.

12. Training

Manage courses under Training Courses; enrollments under Trainings or the employee Trainings tab.

13. Supporting employee data

13.1 Contacts

Belong to the Person: value + contact type + default flag.

13.2 Relatives

Belong to the Employee: full name, relationship type, family allowance flag, phone, notes (lightweight — no separate Person record).

13.3 Qualifications

Academic degree + specialization + institution + graduation date + note.

13.4 Unions

Union, card number, join date, active flag.

13.5 Documents / attachments

Polymorphic files attached to employees and related HR objects (relative, training, qualification, assignment, promotion, penalty, reward, leave, benefit, circular, etc.). Support document type, metadata, expiry, and storage kind.

Employees with portal rights can manage their own attachments within permission limits.

13.6 Employee history

Audit timeline of meaningful changes (assignment, grade, promotion, status, exit, …) used by the Employee history report.

14. Circulars and notifications

14.1 Circulars

Administrative announcements with:

• Title and body
• Audience: All employees, Employee group (e.g. Payroll groups), or Selected employees
• Draft vs Published
• Optional document attachments

Admin path: Circulars (HR.Circulars.Manage). Employees read under portal Circulars.

14.2 Internal notifications

Per-employee inbox: title, message, type, optional deep link, read/unread. Used for leave events, circulars, and similar. Portal includes a notifications page and bell.

15. Employee portal and mobile app

15.1 Portal purpose

Self-service area for the signed-in employee (/hr/employee/..., also My profile), gated by View own employee profile and related own-* permissions.

15.2 Typical portal capabilities

15.3 Personal agenda

Entries: title, notes, start/end, type (appointment / task / note), completed flag, all-day, reminder. Own create/edit/delete/view permissions.

15.4 Mobile APK administration

Employee portal mobile app screen: upload and update the portal Android APK for employees to download. Requires MobileApp.Manage.

16. Dashboard and reports

16.1 HR dashboard

Snapshot metrics such as: total employees, assignments, departments, positions, employment types, active assignments, pending leaves, total leaves, last updated time.

16.2 Reports

Access each report via its own permission under HR.Reports.*.

17. Permissions summary

Permissions are ABP policies under the HR group. High-level split:

17.1 HR administrator (typical)

Full CRUD (as granted) on employees, assignments, lookups, promotions, penalties, rewards, qualifications, relatives, health insurances, trainings, holidays, leaves (including Approve), attachments, change requests, checklists, circulars, mobile app, and reports — plus Change status, Transfer, and optionally Override lifecycle.

17.2 Employee (portal role)

Always align role grants in Administration → Roles with the least privilege needed.

18. Integration with other modules

Appendix A — Quick reference: end-to-end procedures

A.1 Hire and place an employee

1. Ensure lookups and departments exist.
2. Employees → Create (or hire from Recruitment).
3. Complete onboarding checklist items.
4. Assignments → Create (department, position, employment type, start date).
5. Add contacts, qualifications, documents as needed.

A.2 Process a leave

1. Employee requests leave in portal (or HR creates).
2. Approver opens Leaves, approves or rejects.
3. Only Approved leaves consume balance.
4. Use Leaves report for period analysis.

A.3 Exit an employee

1. Employee file → Exits → Create (Draft).
2. Complete offboarding checklist.
3. Confirm exit → status Terminated.
4. Soft-delete only when policy allows (confirmed exit / override).

A.4 Run periodic promotions

1. Open Periodic Promotions.
2. Calculate for one employee or batch.
3. Review eligibility, proposed grade, percentage.
4. Apply when Payroll salary is active.
5. Verify Promotions / employee history.

A.5 Publish a circular

1. Circulars → Create title, body, audience.
2. Attach files if needed.
3. Publish → notifications delivered.
4. Employees read under portal Circulars.

Appendix B — Document control

This guide describes functional capabilities of the HR module as implemented in the Vertex ERP codebase. UI labels may appear in English or Arabic depending on the user’s language setting.