Feat/queue entry metrics endpoint

[shubhangiisinghh]

Description

The Service Queues UI currently fetches active queue entries using generic custom representations:

GET /ws/rest/v1/queue-entry?v=custom:(
  uuid,display,
  patient:(uuid,display,person:(age,gender)),
  queue:(uuid,display,location:(uuid,display)),
  status:(uuid,display),
  priority:(uuid,display),
  startedAt,sortWeight,visitQueueNumber
)

This forces the REST layer to traverse a deep object graph on every request:

QueueEntry
  └─ Patient
       └─ Person
            └─ PersonName
  └─ Queue
       └─ Location
            └─ LocationTags, LocationAttributes...
  └─ Concept (status)
       └─ ConceptNames, ConceptMappings...
  └─ Concept (priority)
       └─ ConceptNames, ConceptMappings...

For a queue board with 50+ patients this causes unnecessary Hibernate
fetches on every page load. Additionally, wait time is currently derived
client-side from startedAt, adding frontend logic that belongs on the
server.

Solution

New endpoint:

GET /ws/rest/v1/queue/metrics?location={locationUuid}
                             [&status={statusUuid}]
                             [&queue={queueUuid}]

Returns a flat JSON array with only what the UI renders:

[
  {
    "uuid": "abc-123",
    "patientUuid": "pat-456",
    "patientName": "John Doe",
    "patientIdentifier": "OM-10045",
    "patientAge": 34,
    "patientGender": "M",
    "queueUuid": "q-789",
    "queueName": "Triage",
    "locationUuid": "loc-001",
    "locationName": "Outpatient Clinic",
    "statusUuid": "s-111",
    "statusDisplay": "Waiting",
    "priorityUuid": "p-222",
    "priorityDisplay": "Normal",
    "startedAt": "2025-03-01T08:30:00.000+0000",
    "waitTimeMinutes": 34,
    "sortWeight": 0.0
  }
]

Files Changed

File	Description
omod/src/main/java/.../web/dto/QueueEntryMetricsResponse.java	New flat DTO — no nested objects
omod/src/main/java/.../web/resources/controller/QueueEntryMetricsController.java	New Spring MVC controller with constructor injection
omod/src/test/java/.../web/resources/controller/QueueEntryMetricsControllerTest.java	7 unit tests using plain Mockito

Key Technical Decisions

1. Flat DTO instead of custom representation
Every field in QueueEntryMetricsResponse is a primitive, String, or
Date. No nested objects. The server resolves patient.person.personName
once and returns a plain patientName string.

2. Constructor injection instead of static Context
The controller receives LocationService and QueueEntryService via
@Autowired constructor injection instead of Context.getService()
static calls. This makes the controller fully testable without PowerMock
or a Spring context.

3. getFirstConceptName() instead of Concept.getName()
Concept.getName() internally calls Context.getAdministrationService()
to resolve locale — which requires a full Spring context and causes
unnecessary overhead in production. Replaced with a helper that calls
concept.getNames().iterator().next() directly, bypassing the locale
lookup entirely.

4. Wait time computed server-side
waitTimeMinutes is computed once on the server from startedAt,
removing the need for the frontend to derive it per patient.

5. Active entries only
criteria.setIsEnded(false) ensures only active queue entries are
returned — no ended entries are fetched or mapped.

Query Parameters

Parameter	Required	Description
location	Yes	UUID of the Queue Location
status	No	Filter by status concept UUID
queue	No	Filter by queue UUID

Tests

7 unit tests covering:

• 400 when location UUID is null
• 400 when location UUID is blank
• 404 when location not found
• 200 with empty list when no entries
• 200 with correct flat fields mapped
• 200 with multiple entries
• 200 with null patient handled gracefully

All tests use plain MockitoJUnitRunner — no PowerMock, no Spring
context required.

How to Test Manually

curl -u admin:Admin123 \
  "http://localhost:8080/openmrs/ws/rest/v1/queue/metrics?location=<locationUuid>"

Related

• Motivation: @ibacher (mentor) noted in the Service Queues GSoC project
  discussion that the frontend relies on unwieldy custom representations and
  that a purpose-built endpoint returning only the required data should be
  built instead.
• Service Queues module: https://github.com/openmrs/openmrs-module-queue

[ibacher]

Two things here:

1. This needs a ticket. If you have not done so, please request Jira access
2. This changes too many unrelated things in one PR. Accumulative changes makes it harder to review your PR. Please keep a PR focused on a single task and leave other refactoring for future PRs.

[ibacher]

Also the change here listed a 3 actually makes this PR perform incorrectly.

[shubhangiisinghh]

Hi @ibacher, apologies for the delayed response. I was away for the
Holi festival .I've requested Jira access and will link a ticket once I have it.

[shubhangiisinghh]

Could you clarify which specific change in point 3 is causing incorrect behaviour? I want to make sure I fix it properly rather than guess. Are you referring to the getFirstConceptName() helper replacing Concept.getName()?

[shubhangiisinghh]

As of now, reverted the unrelated DAO changes. This PR now only adds the new metrics endpoint (3 files: QueueEntryMetricsResponse, QueueEntryMetricsController, and its test).

[RoshanMadival08]

Good idea to create a dedicated metrics endpoint to reduce over-fetching. A few observations:

The flat DTO approach is clean and the constructor injection pattern makes the controller testable without PowerMock, which is a good design choice.
Regarding the getFirstConceptName() helper — as @ibacher flagged, using concept.getNames().iterator().next() without locale resolution can return an unpredictable name depending on the order of concept names stored. Concept.getName() with locale context is safer.
The 7 unit tests cover the important edge cases well, particularly the null patient handling