O3-5692: Build a dedicated REST endpoint for queue entries

[UjjawalPrabhat]

Summary

The Service Queues table currently loads via QueueEntryResource with a deep custom v= representation that pulls every encounter, obs, and diagnosis on each patient's visit. On a 50-entry queue this triggers hundreds of cascading Hibernate loads; ~95% of the bytes are never read by the table.

Adds GET /rest/v1/queue-entry-summary — flat, server-paginated, with previousQueueEntryUuid resolved via a single batch IN-clause query instead of the per-row N+1 path through getPreviousQueueEntry.

Mirrors the three-layer batch pattern from openmrs-module-emrapi PR #250.

Response shape

Before (/queue-entry?v=custom:(…) as requested by the frontend):

{
  "uuid": "...",
  "display": "...",
  "queue":    { "uuid": "...", "display": "...", "name": "...", "description": "...", "service": {...}, "location": {...} },
  "status":   { "uuid": "...", "display": "...", "name": {...}, "datatype": {...}, "conceptClass": {...}, "set": false, "version": "...", "retired": false, "names": [...], "descriptions": [...], "mappings": [...], "answers": [...], "setMembers": [...], ... },
  "priority": { /* same deep Concept shape */ },
  "patient": {
    "uuid": "...", "display": "...",
    "identifiers": [ { "uuid": "...", "identifier": "...", "identifierType": {...}, "location": {...}, "preferred": true, ... } ],
    "person": { /* full person graph */ }
  },
  "visit": {
    "uuid": "...", "startDatetime": "...",
    "encounters": [
      {
        "uuid": "...", "display": "...", "encounterDatetime": "...",
        "encounterType": {...},
        "diagnoses": [ { /* full diagnosis */ } ],
        "obs": [ { /* full obs, recursively */ } ],
        "encounterProviders": [ { /* full provider */ } ],
        "voided": false
      }
      /* …every encounter on the visit, each with its full obs/diagnoses/providers graph */
    ],
    "attributes": [ { /* full visit attributes */ } ]
  },
  "priorityComment": "...",
  "sortWeight": 0.0,
  "startedAt": "...", "endedAt": null,
  "locationWaitingFor": {...}, "providerWaitingFor": {...}, "queueComingFrom": {...},
  "previousQueueEntry": { /* full QueueEntry, recursively */ }
}

After (/queue-entry-summary):

{
  "uuid": "...",
  "patient":  { "uuid": "...", "display": "100GEJ - John Doe" },
  "queue":    { "uuid": "...", "display": "Triage" },
  "status":   { "uuid": "...", "display": "Waiting" },
  "priority": { "uuid": "...", "display": "Not urgent" },
  "priorityComment": "...",
  "startedAt": "2026-05-25T09:00:00.000+0000",
  "visitUuid": "...",
  "visitStartDatetime": "2026-05-25T08:55:00.000+0000",
  "previousQueueEntryUuid": null
}

Relate Issue

O3-5692

[jwnasambu]

@UjjawalPrabhat this is a good progress . Kindly make the following updates here:

• Update SUMMARY_REPRESENTATION to include patientIdentifier.
• Add logic to rename patientIdentifier to identifier and flatten the patient object.

[jwnasambu]

Also create this file to include test cases for
getQueueEntrySummaries_shouldReturnPaginatedSummariesWithIdentifier,
shouldHandleTotalCountRequest, and shouldReturnEmptyListWhenNoResults. I know the PR originally focuses on DAO tests but without Controller tests there is
no verification that the final JSON keys like identifier or visitUuid are correctly
transformed for the frontend.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[chibongho]

Hi @UjjawalPrabhat, some questions I have:

• Are you sure that visit.encounter.obs and previousQueueEntry are pulled in recursively? Looking that this from the O3 service queues app, I don't think we are doing that.
• I'm not surprised that the frontend is pulling more data than is needed. That said, can't we fix that by fixing the custom:() rep in the frontend?
• You're right that previousQueueEntry is not that efficient. If /queueEntry?custom(previousQueueEntry) returns N queue entries, then for each N of them, we make one additional request for its previous queue entry. It looks like this will help reduce it to one query instead. That said, is it that a big performance improvement to warrant having a specialized endpoint?
  • preivousQueueEntry is unfortunately not well implemented, see code. The right way to do it would have been having an actual preivous_queue_entry column in the DB. That way, we could have added the following to QueueEntry.java, which would fix the performance issue:

        @BatchSize(size = 100) // this will automatically batch the queries for previousQueueEntries for a List<QueueEntry> returned by hibernate
        @Column(name = "previous_queue_entry")
        private QueueEntry previousQueueEntry;