Skip to main content

Onboarding & Offboarding Troubleshooting

Summary​

Start with the visible symptom, current lifecycle state and routed boundary. Use authorized health, correlation, audit and event evidence; do not modify records, replay messages or collect sensitive values while diagnosing.

Audience​

Support, QA, lifecycle operators and engineering escalation teams.

Symptoms​

Common symptoms include a missing route or menu entry, an empty or partially loaded workspace, validation rejection, a completed onboarding without a visible employee, missing exit decision actions, a pending access revoke, or a report/workspace mismatch.

Cause​

Likely causes are role or module visibility, current lifecycle state, client validation, gateway routing, a failed synchronous handoff, delayed event projection, an independently unavailable report source, or a suppressed subsection load error.

Resolution​

Use the matching symptom section below. Establish the current server-returned state and first failed boundary before retrying. Escalate with sanitized time, page, action category and authorized correlation evidence; do not modify records or replay work from this guide.

Validation​

Confirm the intended page and status now load, the immediate action has one authoritative outcome, and any required downstream record or projection exists. A success banner alone is not end-to-end validation.

Troubleshooting​

Page is unavailable or absent from navigation​

Confirm the signed-in user has the expected module visibility, role and permission and that the protected route is allowed. Remember that Exit has no verified menu item. A hidden item is not proof that the backend is disabled. Escalate repeated access denial with the page name, time window and sanitized correlation reference.

Onboarding list is empty or an accepted candidate is missing​

Confirm the offer reached an accepted or signed state and that search text is cleared. Check whether the workspace load is unavailable and which routing mode served Recruitment. Do not recreate the offer until the existing outcome is known.

Offer response fails​

An opaque action link may be invalid, expired or already terminal. Ask the candidate to use the intended link through the approved channel; never request that the link be pasted into a ticket. If the state is not terminal, use correlated Recruitment diagnostics.

Onboarding completion fails validation​

Check employee code, login email, joining date, department, designation and the compensation field required by the selected employment mode. Confirm the designation belongs to the selected department. Backend validation may add constraints not shown by the UI.

UI says complete but no employee is visible​

Treat this as a handoff or compatibility-boundary issue. Establish which Recruitment and Employee implementations were routed, whether the onboarding aggregate completed, whether synchronous Employee provisioning succeeded, and whether the employee record exists. Do not submit completion again until idempotency and the first outcome are known.

Downstream payroll, leave or other readiness is delayed​

Employee creation and downstream projections are separate. Inspect authorized Employee event staging and consumer evidence. Employee event relay registration is not verified, Attendance and Asset are not confirmed Employee-lifecycle consumers, and Notification consumes only a limited lifecycle contract. Escalate to the first missing projection owner.

Exit action buttons are missing​

Confirm current status and server-authorized role/scope. Approve/Reject appears only for Submitted or Manager Approved rows; rollback decisions appear only for Rollback Requested. The current employee UI does not originate rollback requests.

Exit page is partially empty​

Some startup reads suppress individual failures. Check which subsection is absent—employee data, exit requests, notice settings or revoke queue—then inspect the corresponding authorized service evidence rather than assuming “no records.”

Access revoke remains pending​

Confirm the exit is approved, the effective last-working date has passed, the account is not already revoked, and the operator can process the queue. Processing is an explicit confirmed action, not browser polling. Escalate a failed action with sanitized status and correlation evidence.

Report value differs from the workspace​

Recruitment dashboards can fall back to calculations from workspace rows, and report tabs load independently. Compare the source availability and date window. Offboarding has no dedicated verified analytics source.

Source References​

  • UI/salary-ui/apps/client-hrms-portal/src/pages/hr/RecruitmentOnboardingPage.tsx
  • UI/salary-ui/apps/client-hrms-portal/src/pages/hr/HrOperationsPage.tsx
  • microservices/src/gateway-api/Program.cs

See Also​

Keywords​

  • Troubleshooting
  • Missing employee
  • Pending access revoke

Revision Information​

  • Status: Draft
  • Last reviewed: 2026-07-20
  • Review cycle: Quarterly