Worklist Testing Plan: How to know if worklists are working as expected

Purpose and new direction

This is a documentation and content-planning issue built on the completed Sonador worklist implementation. Its goal is to turn the implementation record, workflow design, and functional-test evidence into two reusable, user-facing explanations:

  1. A public blog post that explains how Sonador worklists coordinate imaging review, assignment, access, and review history.
  2. A case study for the Sonador User Manual that walks a reader through the review process from request to completion.

The engineering history remains here as the evidence base for those deliverables. Unfinished implementation ideas are preserved below as related follow-up work, but they are not completion criteria for this documentation issue.

Deliverables

1. Blog post

Produce a narrative article that:

  • Starts with the operational problem: imaging studies need to be routed to the right reviewer, reviewed consistently, and handed off without losing context.
  • Explains how a worklist item ties a study to a group and an assigned user while carrying the requested review, current state, notes, performed procedure, and review history.
  • Shows how assignment and local access-control policy work together so that access follows the active review responsibility.
  • Explains how review state and imaging results are intentionally separate: completing a review is not the same operation as adding tags, comments, measurements, or DICOM-SR content to the imaging.
  • Uses a generic, anonymized review scenario and makes no customer-specific claims.
  • Links readers to the SDK examples and technical references for implementation detail.

Suggested structure:

  1. The review-coordination problem.
  2. Requesting review and assigning responsibility.
  3. Moving through the review lifecycle.
  4. Recording findings against the imaging.
  5. Preserving an auditable history.
  6. Enforcing access as responsibility changes.
  7. Building automated or application-specific workflows with the SDK.
  8. Links to the User Manual case study and technical examples.

2. User Manual case study

Create a task-oriented case study using generic personas such as a coordinator and reviewer. It should demonstrate:

  1. A coordinator requests review of a study and records the requested procedure, priority, and reason.
  2. The worklist item is owned by a group and assigned to an eligible user.
  3. The reviewer opens the Worklist Panel or Rapid Review workflow, starts the review, and adds a transition note.
  4. The reviewer inspects the imaging and records results using the appropriate series tags, comments, measurements, or DICOM-SR workflow.
  5. The reviewer completes the item with a performed procedure and completion note, or cancels it with an explanation.
  6. The reader verifies the resulting state and review-history timeline.
  7. The case study explains the relevant permissions and what happens when a study is reassigned.

The case study should include:

  • Prerequisites and required permissions.
  • The expected state before and after every step.
  • Screenshots or diagrams from a generic Sonador environment when available.
  • A short troubleshooting section covering assignment eligibility, read-versus-write permissions, completed-item locking, and loss of access after reassignment.
  • Links to the SDK notebooks for readers who want to automate the same workflow.

3. Source and traceability record

Keep the published material grounded in the existing tests, examples, and implementation records listed below. Any statement about current behavior should be traceable to a source or reproducible workflow.

The review model to explain

Sonador separates the review process into two complementary steps:

Step What it means Sonador/OHIF surface
Request and perform review A study is queued for review. A worklist item is owned by a group, assigned to a user, and moves through Scheduled → In-progress → Completed or Cancelled. It can carry a structured Requested Procedure, transition notes, a Performed Procedure, and a chronological ReviewHistory. Request Review dialog, Worklist Panel, Rapid Review Toolbar, worklist REST and DICOMweb endpoints, the worklist ACL permission, and local Modify permission for state changes
Record the outcome against the imaging Results are captured on the imaging itself through series tags, study or series comments, measurements, and DICOM-SR content. Orthanc stores DICOM-SR as DICOM resources; consuming applications such as the viewer interpret the document content. Series Tag tool, Measurements panel, comments API, /groups/{gid}/tags, and the tag / tag_modify ACL permissions

These steps are deliberately decoupled. A worklist item's state describes the review process only. Tags, comments, measurements, and DICOM-SR content may be created independently and do not require a worklist item to exist. Both deliverables must make this distinction clear.

Canonical references:

Evidence of current behavior

The following automated coverage is the factual foundation for the blog post and case study.

Worklist API

sonador/ftests/tests_ext_worklists.py — SonadorStudyReviewerWorklistTests

  • Create, read, update, and delete reviewer worklist items through the standard and DICOMweb endpoints.
  • Validate group and user associations, group immutability after creation, and assignment only to users who belong to the owning group.
  • Verify that the worklist ACL permission gates creation and that local Modify is required for a limited user to create or change an item.
  • Verify completed-item locking.
  • Verify Kafka export payloads for worklist items.

Access control and reassignment

tests/tests_sonadoracl_worklist_security.py — SonadorWorklistSecurityTests

  • Verify that reassignment changes access consistently with current responsibility: the previous user loses access and the newly assigned user gains it.

Requested and performed procedures; review history

tests/tests_ext_worklist_procedures.py — SonadorWorklistProcedureHistoryTests, implemented through code.oak-tree.tech/oak-tree/medical-imaging/orthanc-sonador#54 and code.oak-tree.tech/oak-tree/medical-imaging/orthanc-sonador!54

  • Capture Requested Procedure data on creation, including coded sequence, description, priority, reason, and server-side attribution.
  • Treat description-only and code-only facets as valid while rejecting empty, unknown, or malformed procedure content.
  • Create one ReviewHistory entry at creation and one for each state transition.
  • Attach notes to transitions or note-only updates and connect them to the comments API through CommentUID.
  • Preserve chronological review history.
  • Protect the reserved RequestedProcedure, PerformedProcedure, and ReviewHistory metadata from general client Meta writes.
  • Exercise the full limited-user workflow across both endpoint families: request → in progress → completed, with requested procedure, notes, and performed procedure.
  • Exercise cancellation with an explanatory note and enforce completed/cancelled locking.
  • Verify that local View permits reading the item and its history while local Modify is required for state and procedure changes.

Result capture

  • sonador/ftests/tests_ext_tags.py — SonadorTagsApiTests: group tag-definition CRUD using Coded Concepts through /groups/{gid}/tags.
  • sonador/ftests/tests_ext_comments.py and tests/tests_sonadoracl_local_comments.py: study and series comment lifecycle across both endpoint families, including the CommentView / CommentEdit permission matrix.

Supporting behavior

  • tests/tests_ext_ordering.py: the Modified virtual tag orders DICOMweb query results correctly so worklist and upload queues remain coherent.
  • tests/tests_sonadoracl_*.py: the broader local and remote permission matrix for view, modify/remove, comments, queries, and roles.

Editorial and accuracy requirements

  • Use generic organizations, roles, studies, and identifiers.
  • Do not include customer names, customer-specific screenshots, confidential implementation provenance, or competitive comparisons.
  • Clearly distinguish shipped behavior from future ideas.
  • Describe permissions precisely: worklist visibility and state transitions depend on both the worklist permission and local resource permissions.
  • Do not imply that Orthanc parses or indexes DICOM-SR content server-side.
  • Treat the SDK notebooks and functional tests as the authoritative sources for examples and claims.
  • Link technical references rather than reproducing large API payloads in the blog post; the User Manual may include concise, task-focused examples.

Documentation acceptance criteria

  • Blog-post outline reviewed for audience, claims, and public-safe examples.
  • Blog-post draft explains the complete request → review → outcome → history arc.
  • User Manual case study includes prerequisites, permissions, numbered steps, expected results, and troubleshooting.
  • Both deliverables explain the separation between worklist state and imaging results.
  • Reassignment and access-control behavior are included and traced to the functional tests.
  • Requested Procedure, Performed Procedure, transition notes, and ReviewHistory are represented accurately.
  • SDK and technical-reference links have been checked on the published pages.
  • Screenshots contain no customer, patient, credential, host, or other sensitive information.
  • A final technical review confirms that every behavior claim is supported by the current implementation or automated tests.

Related engineering follow-ups — not documentation acceptance criteria

The original issue also recorded implementation ideas that remain useful but should not block the blog post or User Manual case study:

Related records

Project Tracking

OP#83
OP#145

Edited by Sonador ChatGPT