Recruitment Module — User Guide

1. Overview

The Recruitment module runs the hiring pipeline from a headcount request through to creating an employee in HR.

There is no separate workflow engine. Progress is driven by status enums and dedicated actions (Submit, Publish, Commit, Send, Accept, Handoff). Prefer those actions over editing status fields by hand.

Shared with HR: departments, positions, employment types, academic degrees, specializations, institutions, marital statuses, nationalities, religions, person identity, and documents.

2. Getting started

2.1 Prerequisites in HR

Before recruiting:

1. Departments, positions, and employment types exist.
2. Academic degrees / specializations / institutions exist (for candidate and requisition qualifications).
3. Person-related lookups (nationality, marital status, religion) exist if you capture full candidate identity.

2.2 Recommended operating order

2.3 Main navigation

3. End-to-end hiring pipeline

Important: Accepting an offer is not the same as hiring. Hiring completes only when you run Handoff to HR.

4. Job requisitions

A job requisition requests headcount for a department/position before a posting can be published.

4.1 Key fields

4.2 Statuses

4.3 Flow

4.4 Rules

• Edit and delete only while Draft (update resets to Draft).
• Submit: Draft → Submitted.
• Approve: Submitted → Approved or Rejected.
• List filter Without posting helps find approved requisitions that still need a posting.

5. Job postings

A job posting is the vacancy announcement linked to a requisition.

5.1 Key fields

Title, description, requirements, open/close dates, linked requisition, published at / by, status.

5.2 Statuses

5.3 Flow

5.4 Rules

• Edit/delete only in Draft.
• Publish requires linked requisition Approved; sets published timestamp; open date defaults to now if empty.
• Close sets close date if empty.
• Applications can be created only against Published postings.

6. Candidates

A candidate is a person in the talent pool. Creating a candidate also creates (or updates) an HR Person (civil identity), typically keyed by national number.

6.1 Profile data

6.2 Candidate sources

Website, Referral, Walk-in, Agency, University, Social media, Other.

6.3 Rules

• No pipeline status enum on the candidate itself.
• After handoff, the candidate is hired and becomes read-only (profile, qualifications, experiences locked).
• Blacklist can be cleared when handed off as hired.

7. Applications

An application links one candidate to one job posting.

7.1 Key fields

Candidate, posting, applied at, status, cover letter, rejection / on-hold reasons, notes.

7.2 Statuses

7.3 Create rules

• Posting must be Published.
• Candidate must not already be hired.
• Unique pair: one application per candidate per posting.
• Status forced to Applied.
• System auto-creates an uncommitted screening row.

List helpers in the UI/API commonly include: eligible for interview, ready for decision, eligible for offer. After handoff, applications are locked.

8. Screenings

Each application has one screening record (created automatically). Users do not create screenings manually (create API is disabled).

8.1 Fields

Result, score, notes, screened by (person + name from current user), screened at, committed flag. DTO may show candidate/posting and whether an interview already exists.

8.2 Results

Uncommitted vs done is controlled by IsCommitted, not a separate status enum.

8.3 Flow

8.4 Rules

• Update only while not committed.
• Commit stamps screener from the current user’s linked Person and advances the application.
• Rescreen only from committed OnHold.
• One screening per application.

9. Interviews

Interviews are rounds (1, 2, …) on an application after a Passed screening.

9.1 Types

Phone, Technical, HR, Final, Panel.

9.2 Interview statuses

Scheduled, Completed, Cancelled, NoShow, Rescheduled.

9.3 Panel and evaluations

• Panel members: persons on the interview; optional lead.
• Evaluations: evaluator (must be a panel member), score, recommendation, notes, evaluated at.

Recommendations: Strong hire, Hire, Hold, No hire, Strong no hire.

9.4 Eligibility and completion rules

Create interview when:

• Screening committed as Passed.
• No decision yet, or latest decision is OnHold.
• Offer not handed off.
• No other interview still Scheduled.

Creating an interview sets the application to Interview.

Complete interview:

Application summary can show rounds, average scores, dominant recommendation, readiness for decision, and next round number.

10. Decisions

A decision records the hiring outcome for an application after interviews.

10.1 Types

10.2 Ready for decision

Typically:

• At least one Completed interview.
• Zero interviews still Scheduled.
• Not handed off.
• No prior decision, or latest decision is OnHold.

10.3 Rules

• Create requires readiness.
• Create/update/delete locked after handoff.
• Eligible for offer usually means latest decision is Accepted and no offer exists yet.

11. Job offers and HR handoff

11.1 Offer fields

Offer number (auto OFF-{n}), offered salary, employment type, position, department, proposed start date, expiry date, status, sent/responded timestamps, rejection reason, notes, handed-off employee id.

11.2 Offer statuses

11.3 Offer flow

11.4 What Handoff creates in HR

When offer status is Accepted, Handoff:

1. Finds or creates an Employee for the candidate’s Person (active; hire date from proposed start date or now).
2. Copies candidate qualifications that have institution + graduation date into HR qualifications (skips duplicates).
3. Creates an open assignment if none exists (position, department, employment type from offer; contract number = offer number).
4. Sets handed-off employee id on the offer; marks candidate hired; clears blacklist if set.
5. Moves recruitment documents (candidate + that candidate’s application docs) to the Employee.
6. Calls HR hire lifecycle → typically spawns an Onboarding checklist.

Handoff is idempotent if already done (re-syncs candidate/docs). After handoff, recruitment pipeline records for that hire are locked.

Remember: Offer Accept only updates statuses. Handoff is the hire into HR.

12. Dashboard

The recruitment dashboard is an operational board of counts (frontend aggregation), typically grouped as:

Needs attention

• Overdue scheduled interviews
• Interviews due today
• Applications ready for decision

By stage

Use the dashboard to prioritize work without opening every list screen.

13. Permissions summary

Permission group: Recruitment.

Grant Approve to hiring managers/HR approvers, Publish/Close to recruiters who own vacancies, and Handoff to staff who may create employees in HR.

14. Integration with HR

Recruitment does not calculate payroll or attendance; after handoff, continue in the HR (and related) modules.

Appendix A — Quick procedures

A.1 Open a vacancy

1. Create requisition (Draft) → add qualifications → Submit.
2. Approver Approves.
3. Create posting linked to that requisition → Publish.

A.2 Process a candidate through hire

1. Create candidate (+ attachments/qualifications/experience).
2. Create application on published posting.
3. Commit screening as Passed (or Rejected / OnHold).
4. Create interview round(s); add panel and evaluations; complete.
5. Create Accepted decision when ready.
6. Create offer → Send → Accept.
7. Handoff to HR → complete onboarding in HR.

A.3 Decline / stop paths

Appendix B — Document control

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