Organization Troubleshooting
Summary
Use authorized, read-only organization views, employee results, audit/timeline entries, and public-safe event status to identify the owning boundary. Never use direct database edits or include personal, credential, or configuration data in diagnostics.
Audience
- Tenant administrators and implementation partners
- Support, development, QA, and DevOps teams
Purpose
This page provides non-destructive checks for scenarios represented in current source.
Architecture
Symptoms
| Scenario | Symptom |
|---|---|
| Department not available | An active department is absent from selection or lookup. |
| Designation not available | An expected designation is absent or rejected. |
| Employee cannot be assigned | Employee creation or reassignment returns validation failure. |
| Manager assignment rejected | A manager change is not accepted. |
| Organization hierarchy not updated | The chart still shows an earlier reporting relationship. |
| Previous department remains visible | An employee appears under the old department after reassignment. |
| Tenant mismatch | Records cannot be resolved in the active tenant context. |
| Duplicate department/designation | Creation or update reports a code/name conflict. |
| Missing organization context | The service reports missing tenant context or returns no tenant-scoped data. |
| Downstream module is stale | Attendance, Leave, Payroll, Performance, Workflow, or Reporting does not reflect the change. |
Cause
| Scenario | Likely source-supported cause |
|---|---|
| Department not available | It is inactive, belongs to another tenant scope, or the active route reads a different transitional store. |
| Designation not available | It is inactive, tenant-invisible, department-filtered, or stored in the other compatibility boundary. |
| Employee cannot be assigned | The referenced master is inactive/missing, designation and department conflict during creation, or tenant context is absent. |
| Manager assignment rejected | The manager is inactive/missing, is the employee, or is outside the tenant-visible data scope. |
| Organization hierarchy not updated | The UI chart reads the transitional user-manager hierarchy rather than Employee Service reporting-manager data. |
| Previous department remains visible | A cached/read-model view is stale, or the request changed a different compatibility store. |
| Tenant mismatch | Tenant claims/context do not identify the record’s owner. |
| Duplicate department/designation | A normalized code already exists in the tenant; monolith compatibility may also reject duplicate names. |
| Missing organization context | The authenticated request lacks usable tenant identity. |
| Downstream module is stale | No confirmed consumer handles the organization-change event, or the module reads monolith/shared data during transition. |
Resolution
| Scenario | Safe resolution |
|---|---|
| Department not available | Confirm active state, tenant ownership, and approved route owner through authorized views. |
| Designation not available | Confirm active state and any department association; select a compatible designation or request governed master-data correction. |
| Employee cannot be assigned | Correct the referenced active master and tenant context, then retry through the supported application path. |
| Manager assignment rejected | Select another active employee in the same tenant and avoid self-reference. Escalate suspected cycles for review. |
| Organization hierarchy not updated | Compare Employee Service reporting data with the transitional user hierarchy and route the discrepancy to the owning team. |
| Previous department remains visible | Refresh the supported view and compare the authoritative employee result, audit/timeline, and active route owner. |
| Tenant mismatch | Reauthenticate in the intended tenant and verify only non-sensitive tenant identifiers through approved tools. |
| Duplicate department/designation | Reuse/update the existing master when appropriate or choose an approved unique code. |
| Missing organization context | Re-establish the correct authenticated tenant session; do not inject internal headers or bypass authorization. |
| Downstream module is stale | Confirm whether a consumer exists and whether the module reads events or a transitional store; escalate rather than editing data directly. |
Validation
- Confirm the current tenant context without recording claims or tokens.
- Confirm the department/designation exists, is active, and is visible in the intended boundary.
- Confirm the employee’s current department, designation, and manager from the authoritative employee view.
- Confirm the audit/timeline entry and public-safe outbox processing status where applicable.
- Confirm Gateway cutover ownership through approved operational documentation.
- Confirm the downstream service has a verified consumer or documented read path before expecting synchronization.
Escalation
Provide a sanitized correlation reference, UTC time range, affected non-sensitive record reference, active application boundary, expected versus observed state, and checks completed. Route company-profile issues to Platform, organization masters/assignments to Employee Service, access issues to Identity/security, and stale downstream state to the consuming service owner.
Technical implementation
Current source provides tenant filters, active-reference validation, unique-code checks, assignment commands, compatibility routing, audit/timeline records, and outbox events that support these diagnostics.
Source References
microservices/src/employee-service/Application/Organization/Organization.csmicroservices/src/employee-service/Application/Validators/EmployeeCommandValidators.csmicroservices/src/employee-service/Application/Commands/EmployeeApplicationCommands.csmicroservices/src/employee-service/Application/Queries/EmployeeApplicationQueries.csmicroservices/src/employee-service/Infrastructure/EmployeeDbContext.csmicroservices/src/employee-service/Api/EmployeeCompatibilityEndpoints.csmicroservices/src/gateway-api/Program.csControllers/DepartmentsController.csControllers/DesignationsController.csControllers/UserManagementController.cs
Related Articles
See Also
Keywords
- Organization assignment failure
- Tenant mismatch
- Hierarchy inconsistency
Revision Information
- Status: Draft
- Last reviewed: 2026-07-15
- Review cycle: Quarterly