Folks HR

Folks HR is the human-resources side of the Folks suite. It runs the full hire-to-retire employee journey — from a candidate's first résumé upload to a confirmed employee's monthly payslip — on a single SQL-Server-backed engine. Thirteen modules organised into four phases: Recruit · Onboard · Operate · Pay.

Modules in this manual

The hire-to-retire flow at a glance

Database

The engine runs against Folkshr_V1 (production) or FolksHR_MasGen_V1 (development). Connection strings live in appsettings.json; the system will refuse to start if the SQL login or the DB is unreachable.

Authentication and page conventions follow the standard MasGen pattern. This chapter focuses on the roles you'll meet in HR and the conventions you'll see on every screen.

2.1 Logging in

1. Open the FE URL. Login with username & password.
2. JWT issued; redirected to the role's DefaultPath.
3. Login.Status must be Active — Inactive / Blocked rows are admin-only.
4. Candidates use a separate mobile portal (Chapter 7) — not this login.

2.2 Roles you'll meet

2.3 Standard inbox layout

2.4 Common conventions

• Codes are auto-generated. Leave Employee Code, Posting Code, etc. blank when adding — the SP fills them in.
• IsActive / Status flag. Most rows soft-delete via status, never physically remove.
• UserID stamping. CreatedBy / ModifiedBy are filled from the JWT.
• Document attachments. Use the UploadedFiles hook on the API; never store binary in the entity table.
• Inbox-driven workflow. Approvals (leave, posting, offer, attendance regularization) are routed through the workflow listener and surface in the approver's inbox.

UM is shared across all Folks products (HR, Inventory ERP, BackOffice ERP). Treat this chapter as a reference. Modifying UM affects every consuming app.

3.1 Login & RBAC chain

3.2 Tables you may need to know

The Resume module is the hopper. Every CV that enters the organisation — recruiter-uploaded, candidate-self-uploaded, agency-fed, or job-portal-imported — lands as a Resume row, gets parsed, scored, tagged, and becomes searchable in the Talent Pool.

4.1 Sub-modules

• Resume Upload — single or bulk PDF/DOCX intake.
• Resume Search — by skill, location, experience, language, certifications.
• Tagging — manual + auto tags from parsing.
• Scoring — fit-score against an open posting.
• Talent Pool segments — saved searches that auto-refresh as new CVs arrive.

4.2 Key tables

4.3 The intake flow

1. Recruiter clicks Resume → Upload; multi-file picker accepts PDF, DOCX, RTF.
2. SP Resume_Insert creates the header; the file lands in UploadedFiles/Resume/.
3. Background parser extracts skills, education, experience into the child tables.
4. Auto-tagger applies tags from skill list + language.
5. Recruiter reviews on Resume → Detail and adjusts manually if needed.

4.4 Search

The Talent Pool search supports compound filters: skill AND/OR, min experience, language, location, availability, last updated within. Each filter combination can be saved as a Segment and auto-refreshes as new CVs arrive.

A Posting is an open vacancy. The Posting Request is the formal raise — by HR or a department manager — that asks for the position to be filled.

5.1 Posting fields

5.2 Raising a request

1. Open PostReq → New Posting.
2. Fill the fields. Pre-load skills from a Designation template if available.
3. Save as Draft, or click Submit for Approval to push it into the next chapter's flow.

5.3 What happens on submit

• Status flips Draft → Submitted.
• Approver inbox lights up via the workflow listener.
• The posting is not yet visible to candidates — only after Approve.

Postings are approved by HR Head (and optionally Finance, if salary-range is over a threshold). The same Workflow Listener engine used elsewhere in the suite drives this.

6.1 The approval inbox

6.2 Approver actions

• Approve — Status → Approved → Open. Posting becomes visible to candidates on Candidate Mobile.
• Send Back — with comment. Returns to raiser as Draft.
• Reject — Status → Cancelled. Cannot be re-opened (raise a new request instead).

6.3 Auto-close

When the headcount is reached or OpenUntil elapses, the posting moves to Filled or Closed. Closed postings remain in the master for reporting.

The Candidate Mobile module is the public-facing, touch-first experience for applicants. It runs on the same Blazor WASM framework but uses a different layout, separate authentication (candidate accounts, not employee logins), and exposes only the candidate-relevant data.

7.1 What candidates can do

• Self-register and verify mobile + email.
• Browse approved Postings (filtered by location, designation, contract type).
• Apply to a posting — auto-creates a Resume row tied to the application.
• Upload CV, certificates, ID/passport scans, profile photo.
• Track interview status (Scheduled / Done / Awaiting Feedback / Selected / Rejected).
• Accept / decline an offer letter from within the app.

7.2 Architecture note

CandMob shares the same database but uses its own Login type (LoginTypeID = Candidate) so the same UM RBAC engine cleanly separates employee privileges from candidate privileges. There is no overlap between the candidate menu tree and the employee menu tree.

7.3 Key tables (additional to Resume)

The Interview Desk is where shortlisted candidates are scheduled, interviewed and dispositioned. Recruiters book slots, panels record feedback, and the disposition feeds the offer flow.

8.1 The interview lifecycle

8.2 Scheduling an interview

1. Pick the candidate from the Application list.
2. Select Interview Type — Phone / In-person / Video / Panel.
3. Pick panel members (employees marked InterviewerEligible).
4. Slot date/time + room/link.
5. Save — candidate sees the booking in CandMob; panel members get inbox notification.

8.3 Multiple rounds

A single Application can carry many InterviewRound rows. Each round has its own panel, type, and feedback. The candidate's overall disposition rolls up from the last round.

Feedback is structured. Each panellist completes a feedback form right after the round; results are visible to the recruiter only after every panellist has submitted (to avoid bias).

9.1 The feedback form

9.2 Aggregation

Once all feedback rows for the round are submitted, the recruiter sees the consolidated view. The recommendation column is shown as a histogram. The recruiter decides Selected / Rejected / Next-round, and the Application status updates.

A Selected candidate becomes a candidate for an Offer. Offers are generated, approved, sent to the candidate (via CandMob + email), and acceptance is captured back in the system.

10.1 Generating an offer

1. From the consolidated feedback, click Generate Offer.
2. Pick salary structure (or use the posting's salary range).
3. Add allowances, joining bonus (if any), notice period, joining date.
4. Save as Draft → Submit for HR Head approval.

10.2 Offer approval

The same Workflow Listener pattern. Approvers see Offer Code, candidate name, total CTC, joining date and the recruiter's recommendation. They approve, send back, or reject.

10.3 Sending to candidate

Approved offers generate a PDF and push to the candidate's mobile inbox. The candidate has OfferValidityDays (default 7) to accept.

10.4 Acceptance

• Accepted — Application status flips to Hired; Onboarding row auto-creates.
• Counter-offered — candidate proposes adjustments; back to recruiter.
• Declined — Application closed; Resume goes back to Talent Pool.
• Lapsed — no response by validity; same as Declined.

Overseas hires need extra steps — country selection, visa coordination, mobilisation, and per-country compliance. The OverseaseRec module overlays these onto the standard recruitment flow.

11.1 What changes vs domestic

11.2 The overseas flow

11.3 Key tables

Once an offer is accepted, an Onboarding row is auto-created. This is the joiner's checklist of everything that must happen before Day 1 (and a few things on Day 1 itself).

12.1 The standard checklist

• Document collection — ID, passport, education, experience, photo.
• Background verification (BGV) launch.
• IT account creation — email, AD, role assignment.
• Employee ID card issue.
• Biometric enrolment (for Attendance).
• Insurance enrolment.
• Induction training booking (Industrial Training, Chapter 14).
• Day-1 buddy assignment + welcome pack.
• Contract sign-off.

12.2 Configurable templates

Different roles need different checklists. OnboardingTemplate defines reusable checklists per Designation × Country × Contract Type. New onboardings auto-clone from the matching template.

12.3 Status flow

ERD is the master record for every active employee. It pulls from EmployeeReg (created at joining) and adds the deeper detail — family, addresses, nominees, documents, qualifications, certifications, prior experience.

13.1 The ERD page tree

• Personal — name, DOB, gender, marital, nationality, photo.
• Identity — passport, national ID, driving licence, PAN/SSN.
• Contact & Address — current + permanent + emergency contact.
• Family / Dependants — for insurance + leave.
• Education — degree, institution, year.
• Experience — prior employers, designations, dates.
• Certifications — issuing body, expiry date, renewal reminder.
• Documents — every uploaded artefact, with revisioning.
• Bank & Tax — for Payroll's bank file + statutory.
• History — designation/department/salary changes over time.

13.2 Employee Self-Service view

Employees see a read-only version of their own ERD via the Self-Service portal, plus an "Edit and Submit" path for fields they're allowed to change (contact, emergency contact, dependants). Changes flow through HR-Admin approval.

13.3 Document expiry watch

The system watches for expiring passports, visas, certifications and licences and surfaces them in the HR-Admin inbox 30 / 60 / 90 days ahead. Configurable per document type.

Industrial Training covers induction, ongoing refresher, and certification-bearing technical training. It owns programs, schedules, attendance, assessment and certification.

14.1 Program structure

14.2 The trainer's flow

1. Create or pick a Program.
2. Schedule a Session — date, room, trainer.
3. Enrol participants (manual or auto from a Designation rule).
4. Mark daily Attendance during the run.
5. Record Assessment scores.
6. System generates Certificates for those who pass.

14.3 Induction training

Onboarding (Chapter 12) auto-enrols joiners into the Induction program based on their designation. Day-1 attendance gates Joining → Active.

New joiners typically have a probation period. The system tracks it, surfaces probation-end reviews, and flips status from Probation to Confirmed.

15.1 Configuration

Per Designation × Contract Type, probation duration is configured (3 / 6 / 12 months default). On Joining, an EmployeeProbation row is created with EndDate = JoiningDate + duration.

15.2 Probation review

1. 30 days before EndDate, a Probation Review task lands in the line manager's inbox.
2. Manager fills the review form — performance, attendance, behaviour.
3. Decision: Confirm / Extend / Terminate.
4. HR-Admin approves the decision.
5. Status flips on EndDate (or earlier if Terminated).

15.3 What changes at confirmation

• Status: Probation → Confirmed.
• Salary structure may change (some allowances activate post-confirmation).
• Leave accrual rate often increases.
• Insurance dependants become eligible.

The Attendance module accepts multiple sources, reconciles them into a single daily record per employee, and feeds Payroll, Leave and Roster reports.

16.1 Sources

16.2 Daily roll-up SP

A nightly SP Attendance_Daily_Rollup consolidates all sources into AttendanceDaily — one row per employee per date. Status options:

• Present — InTime + OutTime captured, hours within tolerance.
• Late — InTime > scheduled + grace.
• Half-Day — hours below half-day threshold.
• On Leave — approved leave for that date.
• Holiday — public/site holiday.
• Absent — scheduled but no source & no leave.
• Off — roster off-day; no expectation.

16.3 Attendance dashboard

When an employee's record is wrong (forgot to punch, biometric failure, on-duty travel), they raise a Regularization request. Manager approves, the daily roll-up gets corrected, and the audit trail captures the override.

17.1 Raising a request

1. Employee opens Self-Service → Attendance → My Records.
2. Picks a date with the wrong status; clicks Regularize.
3. Enters the correct InTime / OutTime + reason.
4. Submits — request lands in the line manager's inbox.

17.2 Manager action

Manager sees: original record, employee-claimed correction, reason, and supporting evidence (if attached). Approves, sends back, or rejects.

17.3 What happens on approve

SP AttendanceRegularization_Approve updates the matching AttendanceDaily row and writes an AttendanceAdjustmentLog entry capturing the before/after. The Regularization row is marked Approved and remains queryable for audit.

The Duty Roster module plans who works what shift, where, on which days. It is the source of "expected presence" used by Attendance and the basis for shift allowances in Payroll.

18.1 Concepts

• Shift — a named time window (e.g. Day 08:00–17:00, Night 20:00–05:00).
• Shift Pattern — a recurring sequence (e.g. 4-on-2-off).
• Roster — for a Site × Department × Period (week / fortnight / month), the resolved Employee × Date × Shift grid.
• Swap Request — employee-initiated trade with another employee, requires manager approval.
• Holiday Override — site-specific holiday that maps shift to off-day.

18.2 Building a roster

1. Pick the Site, Department, Period.
2. Pick the default Shift Pattern.
3. System materialises the grid with each employee's default shift.
4. Adjust manually for known leaves, training days, project deployments.
5. Publish — visible to employees on Self-Service; informs Attendance roll-up.

18.3 Coverage check

Before publishing, the system checks minimum coverage per shift (e.g. at least 3 engineers on Day shift). Insufficient coverage shows a red banner and blocks Publish until resolved.

19.1 Swap request flow

1. Employee A opens Self-Service → Roster; picks a date; clicks Swap.
2. Picks Employee B (must be qualified for the same shift).
3. Enters reason; submits.
4. Employee B sees the request; accepts or declines.
5. If B accepts → manager approval inbox.
6. On manager Approve → roster is updated; both employees see the new grid.

19.2 Holidays

HolidayCalendar is a per-Site × Year master. When a holiday lands on a rostered shift, the system auto-shifts that day to Off and flags any employee who still worked (likely deserves holiday OT — picked up by Payroll).

19.3 Roster-vs-actual variance

The Variance Report compares what the roster expected vs. what Attendance recorded. Use it to spot:

• Employees frequently absent on rostered days.
• Excessive swaps between specific pairs of employees.
• Shift-allowance mismatches (worked night, claimed day).

The Leave Management module configures leave types, accrues balances, processes applications, and feeds Attendance and Payroll.

20.1 Leave types

20.2 Accrual

Configurable per Leave Type. Most types are monthly accrual on the 1st; some are annual (lump-sum on Jan 1 or anniversary). The SP Leave_Accrue_Monthly runs nightly on the 1st and credits balances.

20.3 Balances dashboard

Self-Service shows the employee their balance per type — opening, accrued, taken, encashed, current. Managers see their team's balances on the same page filtered by team.

20.4 Year-end processing

• Carry-forward applies (capped at policy max).
• Encashable balances above carry-forward cap auto-encash via Payroll.
• Non-carry-forward balances zero-out.

21.1 Apply

1. Employee opens Self-Service → Leave → Apply.
2. Picks Leave Type (only types with positive balance + within rules show).
3. Picks From / To dates; system computes working days using site holiday calendar + roster.
4. Enters reason; optionally attaches medical certificate (mandatory for SL > 2 days).
5. Submits — Application moves to Submitted; lands in line manager's inbox.

21.2 Manager approval

• Approve — application status flips to Approved; Attendance overrides for the dates.
• Send back — comment, returns to employee.
• Reject — application closed; balance untouched.

21.3 Multi-level approval

Long leaves (configurable threshold, default >5 days) need second-level approval (HR Head). The Workflow Listener handles the second hop automatically.

21.4 Cancellation

Approved leave can be cancelled by the employee (before start) or by HR-Admin (anytime). Cancellation restores the balance and reverts Attendance to its prior state.

Payroll is the most configurable module. Salary structure defines what an employee earns and what is deducted, broken down into components.

22.1 Components

22.2 Structure assignment

• Template — per Designation × Country × Contract Type.
• Override — per-employee tweak (e.g. retention bonus).
• Effective dating — every change carries a from-date; the run uses the structure effective on the run date.

22.3 Master tables

• SalaryComponent — master list (code, name, type, taxable flag).
• SalaryStructureTemplate + ...Component — reusable structure.
• EmployeeSalaryStructure + ...Component — per-employee live structure with effective dates.
• EmployeeLoan + ...Schedule — loan ledger feeding deductions.

23.1 Variable earnings

23.2 Statutory deductions

Driven by CountryComplianceProfile. The profile tells the engine which slabs to apply (income tax brackets), which percentages (PF, ESI, social-security), and which caps. Updating the profile mid-year is allowed — the run uses the profile effective on the run date.

23.3 Loan management

Loans are issued via the HR-Admin Loan page. Each loan has principal, interest, EMI, tenure. Payroll deducts the EMI per run until tenure ends. Early settlement is supported.

23.4 Reimbursements

Employees submit reimbursement claims (travel, mobile, internet) with supporting bills. Manager approves, finance verifies, and the approved amount is added to the next Payroll run as a tax-free or taxable line per policy.

The Payroll Run is the monthly compute. It pulls Attendance, Leave, Roster, Loans, Reimbursements, applies the Salary Structure, runs Statutory, and produces Payslips.

24.1 The run pipeline

24.2 Pre-run checklist

• Attendance cut-off date locked.
• Pending leave applications resolved.
• Pending attendance regularizations processed.
• Reimbursement claims approved or deferred.
• Loan adjustments verified.
• New joiners and exits effective for the period flagged.

24.3 The compute

1. Open Payroll → Run → New Run; pick Period (month/year) and Group (typically Country × Designation Band).
2. Click Compute. The SP Payroll_Compute_Run creates a PayrollRun header and per-employee PayrollRunLine rows with all components.
3. Review on the Review screen — outliers (very high/low) are flagged.
4. Drill into any line to see the breakdown: every earning, every deduction, taxable, net.
5. Click Approve. SP Payroll_Approve_Run locks the run and generates Payslips.

24.4 Payslip

One PDF per employee, generated server-side. Layout includes: header (period, employee, designation), earnings table, deductions table, net pay, year-to-date summary, and (optionally) leave balance summary. Payslips are emailed and also visible in Self-Service.

25.1 Bank file

From the approved Payroll Run, generate a Bank Disbursement File in the format required by your bank (commonly NEFT/RTGS/ACH CSV, but configurable). The file is downloadable, signed, and uploaded to the bank portal manually or via an integration.

25.2 Statutory outputs

• PF Return — per-employee PF + employer PF, in the country's required format.
• ESI Return — Social-security challan format.
• Income Tax — Withholding statement / TDS file.
• Form-16 / Annual Tax Statement — generated annually for each employee.

25.3 Reconciliation

Once the bank confirms disbursement, the Reconcile screen marks each employee's payment as Settled and clears it. Failed payments stay as Pending with a reason for HR/Finance to fix.

Three persona dashboards land on login depending on role.

27.1 HR Admin dashboard

• Headcount KPI tile + last-30-day trend.
• Open Postings count, oldest open, candidates pending interview.
• Today's Present / Late / Absent / Leave breakdown.
• Pending approvals (Postings, Offers, Leave, Regularization).
• Document expiries within 30 days.

27.2 Recruiter dashboard

• My open Postings + applications-per-posting.
• Today's interviews + this-week pipeline.
• My funnel — last 30/60/90 days.

27.3 Line Manager dashboard

• Team count + today's attendance.
• Pending Leave + Regularization approvals.
• Team Roster preview for the next 7 days.
• Roster Variance summary for the past month.

28.1 Notifications you'll see in the Inbox

• Posting submitted for approval.
• Interview scheduled / feedback due.
• Offer ready for approval.
• Leave application submitted (manager).
• Attendance regularization request.
• Probation review due (line manager + HR).
• Document expiring within 30 days (HR-Admin + employee).
• Payroll run ready for review.