Skip to main content

Employee Troubleshooting

Summary​

Public-safe triage across the Employee UI, current monolith compatibility API, extracted Employee Service, gateway, persistence, and messaging boundaries.

Audience​

  • HR administrators, support engineers, developers, QA engineers, and DevOps engineers

Symptoms​

Use this section when Employee access, listing, mutation, assignments, timeline, events, persistence, or compatibility behavior differs from the source-confirmed expectation.

Scope​

Public-safe triage across the Employee UI, current monolith compatibility API, extracted Employee Service, gateway, persistence, and messaging boundaries.

Cause​

Likely causes​

  • Authentication, feature, tenant, or access-scope rejection
  • Current route destination or identifier family differs from the caller assumption
  • Validation, persistence, migration, or downstream delivery issue

Safe diagnostic steps​

  1. Start with the decision tree and identify route source before testing deeper layers
  2. Use synthetic reproduction, safe status categories, correlation identifiers, and service health
  3. Compare the symptom with the dedicated topic page

Resolution​

Safe resolution​

  • Correct only approved session/configuration/routing conditions through their owners
  • Use documented application workflows; never edit production data or replay events ad hoc

Validation​

Repeat the smallest safe synthetic check and confirm expected status, tenant scope, and route source.

Evidence to collect​

Time window, sanitized route category, status, correlation identifier, route source, service version, and recent change.

Escalation​

Use the support model; security-sensitive or personal-data incidents follow security escalation.

Source References​

  • docs/modules/employee/technical/known-limitations.md
  • microservices/src/employee-service/Program.cs
  • microservices/src/gateway-api/Program.cs

See Also​

Keywords​

  • Employee troubleshooting
  • Troubleshooting
  • safe diagnostics

Revision Information​

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