Skip to main content

Asset Troubleshooting Overview

Summary​

This section provides a structured, non-destructive approach to diagnosing issues in HR Suit Asset Management. Every procedure here is read-only and observational: you gather evidence, correlate it against expected behavior, and route the finding to the correct owner. No procedure in this section changes data, replays events, edits outbox rows, restarts brokers, or runs migrations or backfills. Diagnosis stops at the point where a change is required, and the change is handed to the responsible team through the escalation path.

The Asset Management service is part of a private service mesh. Its native and compatibility endpoints are anonymous and tenant-scoped by design, and the frontend portal hides navigation rather than enforcing backend role gates. Understanding this posture is essential before interpreting any symptom, because many apparent "access" or "missing data" issues are actually tenant-context or routing conditions rather than defects.

Audience​

Support engineers triaging tickets, developers investigating service behavior, QA engineers reproducing conditions, DevOps engineers reviewing routing and messaging, solution architects assessing integration boundaries, security engineers reviewing the authorization posture, and product owners tracking impact.

Reference Content​

The non-destructive method​

  1. Reproduce the symptom and record exactly what was observed, including which portal screen or endpoint was used.
  2. Confirm tenant context first. A large share of asset symptoms trace to wrong or missing tenant context, because reads are scoped by EF global query filters.
  3. Determine which backend served the request. The gateway emits an X-Gateway-Route-Source response header (values asset-service, asset-service-shadow, or monolith) that tells you whether the asset-service, its shadow, or the monolith answered.
  4. Read the relevant read-only surfaces: tenant-filtered lists, the compatibility workspace projection, and the read-only outbox diagnostics endpoint.
  5. Collect correlation identifiers, route-source headers, and timestamps as evidence.
  6. Route to the correct owner. Do not attempt data repair from this section.

What is safe to do​

Listing assets for a tenant, reading compatibility workspace projections, reading outbox row metadata through the diagnostics endpoint, inspecting response headers, and comparing observed status against the documented state machine are all safe, read-only actions.

What is never in scope here​

SQL, database edits, event replay, outbox row edits, broker commands, migration or backfill commands, and credential inspection are out of scope for troubleshooting and must be handled by the owning team under change control.

Page index​

  • Troubleshooting Authentication and Authorization
  • Troubleshooting Tenant Context
  • Troubleshooting Asset Create and Update
  • Troubleshooting Duplicate Asset Code
  • Troubleshooting Asset List and Detail
  • Troubleshooting Asset Assignment
  • Troubleshooting Asset Return
  • Troubleshooting Asset Requests and Approval
  • Troubleshooting Asset Workflow Callbacks
  • Troubleshooting Damage, Loss, Retirement, and Deletion
  • Troubleshooting Asset Documents
  • Troubleshooting Asset Notifications
  • Troubleshooting Asset Outbox and Messaging
  • Troubleshooting Asset Gateway and Compatibility
  • Troubleshooting Asset Audit and Timeline
  • Troubleshooting Asset Migrations and Backfill
  • Asset Diagnostic Decision Tree

Source References​

  • microservices/src/asset-service/Api/AssetEndpoints.cs
  • microservices/src/asset-service/Api/AssetCompatEndpoints.cs
  • microservices/src/gateway-api/Program.cs
  • microservices/scripts/smoke-asset.ps1

See Also​

Keywords​

asset troubleshooting, read-only diagnostics, evidence collection, tenant context, route source

Revision Information​

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