Feature idea: Weasis as a PS3.18 UPS-RS User Agent (per-study "AI tasks" menu)

[clicker71]

Motivation

Weasis speaks DICOMweb for QIDO/WADO/STOW but has no Unified Procedure Step (UPS-RS, PS3.18 Section 11) client. IHE AIW-I deployments already mint UPS workitems on the archive (origin server); a viewer-side User Agent would let a radiologist see and act on those tasks without leaving Weasis.

The idea (a standard role, not an AI feature)

Implement the PS3.18 11.1 "User Agent" role as a small, per-study menu:

• Search For Workitems (11.9, RAD-81) to list rows for the open study. The study filter is viewer-internal - by Study UID inside Input Information Sequence (0040,4021). Study UID is not a standard search matching key, so the wire stays untouched.
• Retrieve Workitem (11.5, RAD-83) to read a row's Output Information Sequence (0040,4033) when a result is ready.
• Create Workitem (11.4, RAD-80) to start a task addressed to the archive's AI station.
• Change Workitem State (11.7) is named for completeness; the menu's "Run" action only creates.

Menu states, driven by Procedure Step State (0074,1000) + Output Information Sequence: COMPLETED with outputs -> "Ready"; IN PROGRESS -> "Running"; SCHEDULED (AI station) -> "Queued"; SCHEDULED (manual station) -> "Run". Labels come from Workitem Code Sequence (0040,4018) CodeMeaning - no local label table.

Why standard

Every step above is a named PS3.18/RAD transaction (11.1/11.4/11.5/11.9, RAD-80/81/82/83/85, AIW-I 4.80.4.1.2.1). No proprietary keys on the wire.

Proven against a conformant origin

Tested end-to-end against our DICOMweb server (public conformance statements: dicomweb-conformance-statement.md and dimse-bridge-conformance-statement.md) plus a published demo pack. Full citation list is ready to attach to the PR.

Questions before I write the PR

1. Is this feature in scope for Weasis?
2. Should the PR be one unit (the menu), or first a minimal generic UPS-RS client layer with a small consumer, then the menu on top?
3. Any preference on where the menu lives (a toolbar action per study)?

I will implement and test the change myself; I am the author and available for review.

[nroduit]

A UPS-RS client is in scope for Weasis, provided it stays generic and optional. A few points before starting a PR:

Structure

• Two steps: first a generic UPS-RS client layer (Search, Retrieve, Create, Change State), then the per-study menu on top.
• Packaged as a separate module, disabled by default and enabled per DICOMweb node in the configuration. It should degrade gracefully when the server does not support UPS-RS.

Search / filtering

• Please filter server-side rather than in the viewer. Patient ID and Referenced Request Sequence > Accession Number are required matching keys, and Input Information Sequence > Study Instance UID is an optional one (PS3.4 Table CC.2.5-3).
• Fetching a broad worklist and filtering locally raises performance and privacy concerns (workitems of other patients).

Workflow

• "Run" on an existing SCHEDULED workitem should not create a duplicate. Either claim it via Change Workitem State (11.7) with a Transaction UID, or only offer Create when no matching workitem exists.
• Without Subscribe/WebSocket support, please make the polling interval configurable and conservative.
• Reuse the existing DICOMweb authentication. Write operations (Create/Change State) must be allowed only when explicitly configured.
• Outputs from the Output Information Sequence should be loaded through the existing WADO-RS retrieval path.

Validation

• Besides your server, please test against a public open-source implementation such as dcm4chee-arc.

UI

• A contextual action on the study in the DICOM Explorer seems more appropriate than a global toolbar button.

[clicker71]

Hi Nicolas,

Thanks — that's a clear, actionable breakdown. We agree with the structure and
nearly all of it. Where we stand, and a few questions where your call matters.

Agreed as-is:

• Two-step structure: a generic UPS-RS client layer first (Search, Retrieve,
  Create, Change State), then the per-study menu on top.
• Separate module, disabled by default, enabled per DICOMweb node, degrading
  gracefully when the server does not speak UPS-RS.
• Server-side filtering. On our side this surfaced a real gap: Clarus currently
  supports Patient ID but NOT Accession Number (0040,A370) or Study Instance UID
  (0040,4021) as UPS-RS Search keys. Both are standard PS3.4 Table CC.2.5-3 keys,
  so we are adding them now — a conformance gap on our side, not a design question.
• Claim-vs-create: "Run" claims an existing SCHEDULED workitem via Change State
  (11.7); Create is offered only when no matching workitem exists.
• Reuse of the existing DICOMweb auth; write operations (Create/Change State) only
  when explicitly enabled.
• Outputs loaded through the existing WADO-RS retrieval path.
• Configurable polling fallback (conservative default) when Subscribe/WebSocket is
  unavailable.
• Validation against dcm4chee-arc.

Questions where your call matters:

1. Where should the generic client live? The DICOMweb HTTP+JSON primitives
   (org.weasis.dicom.web., org.weasis.dicom.mf.) live in weasis-dicom-tools.
   Should the generic UPS-RS transport layer go there (a PR to that repo), or in
   the main Weasis repo alongside the explorer? The per-study menu has to live in
   the main repo either way.
2. Attach point. In 4.x the DICOM Explorer context menu is series-scoped — there
   is no study-level context menu. We see three options: (a) a series-scoped
   "AI tasks" submenu for the study of the right-clicked series (minimal change),
   (b) a listener on the StudyPane header, (c) an on-image ViewButton like the
   existing PR/segmentation buttons. Your message says "contextual action on the
   study in the DICOM Explorer", which we read as (a) or (b) — but (c) reuses the
   PR-button mechanism and is closest to how PR/SEG toggles already look. Which do
   you prefer?
3. Code catalog. The set of AI task codes a node offers — a per-node config list,
   or a single global list? (We would default to per-node.)
4. Transaction UID. For Claim (Change State), is a freshly minted DICOM UID
   (2.25 root) acceptable?
5. dcm4chee-arc version. Which version should we pin for the e2e validation?

Plan: we'll implement the generic client + the menu as one effort, validated
end-to-end against Clarus and dcm4chee-arc before opening the PR(s) — so the
evidence is reproducible rather than asserted.

[clicker71]

Thanks for the detailed breakdown. Based on your guidance, here is how we see the v1 — a separate weasis-dicom-ai module adding a dockable viewer tool, no core change.

1. Module and roles

2. Visibility — nothing is shown unless there is something to do

3. RUN flow

v2 — what we would like next (needs a small core extension point)

The dockable tool is a v1 compromise. What we actually want is the behaviour the RTSTRUCT/PR badges already have: a small icon on the study/series preview plus a contextual action, shown only when there is a pending AI task — nothing otherwise. That needs a plugin-provided icon supplier consulted by SeriesThumbnail (e.g. ThumbnailBadgeFactory), separate from #935.

One open question: OAuth2

We reuse the node auth for headers + Basic. OAuth2 (AuthMethod) needs a node lookup by URL and we have no OIDC origin to validate against — is OAuth2 a merge requirement, or acceptable as a follow-up after v1?

[nroduit]

Thanks for the detailed v1 and the diagrams. Here are the answers to your open questions, a few
corrections to the workflow, and some constraints coming from the next major version so the
plugin does not have to be rewritten when it ships.

Where the code goes

1. Generic client: already in weasis-dicom-tools. A UPS-RS client landed on master
   (org.weasis.dicom.web.UpsRS, UpsQuery, UpsConfig, UpsResponse, ProcedureStepState,
   AuthorizationProvider, commit c58821c). It covers Create, Retrieve, Update, Change State,
   Request Cancellation, Search, Subscribe / Unsubscribe / Suspend and the WebSocket event
   channel (PS3.18 §11.4–11.13), with unit tests against a recording HTTP server. Please build
   on it instead of adding an UpsWire layer. It will be released before your PR can be merged;
   until then build the library from source.
2. Keep the OSGi surface minimal. The next major version replaces the OSGi framework with
   a lighter plugin system (@Component, BundleContext and the OSGi preferences service go
   away; InsertableFactory and the tool types stay). Keep the plugin wiring in one activator
   class and keep the rest of the code free of OSGi imports, so the port is a matter of
   replacing that class.
3. Headless service first, UI as a client. Features are moving to a model where the logic
   lives in a headless service and every action is also reachable as a command ($ups:...),
   usable from launch arguments, weasis:// links and scripts. Please structure the module that
   way from the start: a UpsService (search, run, cancel, load outputs for a study) with no
   Swing in its API, and the tool calling it. The verbs themselves can come with the port;
   the split is what matters now. Workitem listings carry patient identity, so they must go
   through the same display-masking path as the rest of the explorer.
4. Module name. weasis-dicom-aiw rather than weasis-dicom-ai: as you wrote, this is a
   standard role, not an AI feature.

Attach point

I still need to evaluate the best option for the explorer integration (menu contributor, badge, or both), so let us keep the attach point for a second phase. For the first PR, the generic client layer plus the UpsService and its tool are enough; the UI entry point can change without touching them.

Two corrections to the workflow

• Do not claim a SCHEDULED workitem with Change State. Setting IN PROGRESS makes Weasis the
  performer and locks the workitem with its Transaction UID, so the AI station can never pick
  it up. My earlier suggestion was wrong on this point. For a workitem SCHEDULED on a manual
  station, the right transaction is Update Workitem (§11.6), allowed without a Transaction
  UID while SCHEDULED, to re-address the Scheduled Station Name Code Sequence to the AI station.
  Otherwise Create. Change State is only for steps Weasis performs itself. Please also offer
  Request Cancellation (§11.8) for a queued task.
• Filter on Referenced Request Sequence, not Input Information Sequence. , need to be confirmed

Remaining answers

• Catalog. Per node, and distributable with the configuration (properties or the
  preferences service) so a site can manage it centrally. Avoid a modality-to-task table inside
  the plugin; where the server exposes them, read the available codes from its SCHEDULED
  workitems (need to be confirmed).
• Transaction UID. Do not mint it with a hard-coded 2.25 root: generate it with dcm4che
  UIDUtils.createUID(), whose root Weasis configures at start-up from the
  weasis.dicom.root.uid property (DicomCodec calls UIDUtils.setRoot), so a site's own
  root applies to every UID Weasis creates, this one included. You only need a Transaction UID
  if Weasis performs a step itself.
• dcm4chee-arc. Validate against the current 5.34.x image (UPS-RS and WebSocket
  subscriptions are supported).
• OAuth2 is not a follow-up. AuthMethod.getToken() / resetToken() in weasis-core map
  directly onto AuthorizationProvider.bearer(supplier, onRejected). A DicomWebNode carries
  one base URL and an authMethodUid; match the node on the URL prefix of the study's
  Retrieve URL. For studies opened through $dicom:rs the auth method is in RsQueryParams.
• Polling. UpsRS.openNotificationChannel gives the event reports; fall back to a
  conservative poll (scheduler of DicomTaskManager) only for studies that are open, and stop
  when the tab closes.
• Outputs. Load the Output Information Sequence references through RsQueryParams with the
  node URL and auth UID (the $dicom:rs path). SEG, RTSTRUCT and SR results then get their
  thumbnail badges for free.

[clicker71]

Thanks for the detailed answer - this is exactly the steer we needed
before touching code. Before starting the first PR we checked the two
items you flagged "need to be confirmed" against the standard. Sharing
what we found; we would welcome a second look.

1. Referenced Request Sequence vs Input Information Sequence

PS3.4 (2026d, current edition) Table CC.2.5-3 (UPS SOP Class N-CREATE/N-SET/N-GET/
C-FIND Attributes) gives the C-FIND matching-key requirements for both
sequences:

• Referenced Request Sequence (0040,A370): Matching Key R (required).
  Inside it: Accession Number (0008,0050) R, Requested Procedure ID
  (0040,1001) R, Study Instance UID (0020,000D) O.
• Input Information Sequence (0040,4021): Matching Key O (optional).
  Inside it (via the CC.2.5-2c macro): Study Instance UID (0020,000D) O.

Our reading of your correction: Referenced Request Sequence is the
portable path, because a conformant origin must support querying by it,
while Input Information Sequence is optional and a server may legally not
filter on it. We saw exactly that in practice - against dcm4chee-arc
5.35.2 (AE DCM4CHEE, UPS-RS service class enabled for that AE) a
StudyInstanceUID search key is ignored and all workitems are returned,
which is conformant behaviour for an optional key.

One detail worth noting: Study Instance UID is reachable in both
sequences, and Accession Number only in Referenced Request Sequence. So
filtering on Referenced Request Sequence covers both keys, which is
probably the cleanest fit for a viewer that knows the study. Either way
your direction holds, and we plan to filter on Referenced Request
Sequence. If you prefer Input Information Sequence for any reason, we can
switch - but the standard and the dcm4chee behaviour point to Referenced
Request Sequence.

2. Catalog from SCHEDULED workitems

The same table types Scheduled Workitem Code Sequence (0040,4018) and
Procedure Step State (0074,1000) as Required matching keys. So "read the
available task codes from the origin's SCHEDULED workitems" is a plain
UPS Search with state=SCHEDULED, collecting the distinct (0040,4018)
values - nothing non-standard. We will do that when the origin exposes
UPS-RS, and fall back to the per-node catalog otherwise.

3. One small thing before we build on UpsRS

While reading the UPS-RS client on master (c58821c), we noticed
updateWorkitem puts the Transaction UID in the query parameter
?transaction= (UpsRS.java). PS3.18 11.6.1 writes the request as
POST /workitems/{workitem}?{TransactionUid}, so the parameter name the
standard fixes is TransactionUid - a strictly conformant origin reads
exactly that spelling.

Since we plan to build on your client rather than fork it, we would rather
flag this now than let the A/B harness find it later: could the client
align to TransactionUid? For context, dcm4chee-arc is lenient and also
accepts transaction-uid, which is probably why this has not surfaced
there.

Not blocking for the first PR - the SCHEDULED re-address is transaction-less -
but it matters the moment Weasis itself updates a workitem it owns. Happy to
be corrected if the client's spelling is intentional.

Side notes, in case useful

• We run UPS-RS A/B tests against dcm4chee-arc 5.35.2 as a reference
  implementation (Create body rejections, ChangeState requester, Update
  spellings, search-key filtering). The search-key result above comes
  from that harness; the full side-by-side comparison is published at
  https://github.com/clicker71/clarus-pacs/blob/main/interop-comparison.md
• The demo pack we ship for the handover is now WSI-ready: built with the
  transcode feature and an instance-size ceiling of 16 GB. It is verified
  on a real 13.09 GB whole-slide file (161191 frames): STOW completes with
  peak RSS around 10 MB (pre-fix: 12.9 GB), and /frames/{N} is served by
  bounded byte-range reads.
  https://github.com/clicker71/clarus-pacs/releases/tag/totalseg-demo-v0.3

None of this changes the module and service split you set out; we just
wanted to close the two "confirm" items before the first PR.

P.S. A small direction for a later version, in case it is useful: once the
dropdown ships, we would like a little robot icon on the study/series preview
whenever a study has a SCHEDULED AI task, so a doctor sees at a glance that AI
work is pending. The icon would disappear once every task is COMPLETED (or
CANCELED), and never appear for a study with no tasks. We understand this
touches core surfaces, so it is only an idea to keep in mind - not part of
this PR.

[nroduit]

Thanks for checking both items. Second look, with two corrections on my side.

1. Search keys. Agreed on Referenced Request Sequence. One precision for your harness: the
   top-level Study Instance UID is an optional key that dcm4chee-arc does not index (so "ignored"
   is conformant), but it does honour the nested ReferencedRequestSequence.StudyInstanceUID.
   Use PatientID + ReferencedRequestSequence.AccessionNumber, else
   ReferencedRequestSequence.StudyInstanceUID, and fill both on Create.
2. Catalog. Right, Scheduled Workitem Code Sequence is a required matching key, so filtering
   by code is portable. The objection is elsewhere: a ProcedureStepState=SCHEDULED search
   returns the workitems of every patient (the privacy point of 09-30), and in AIW-I the Task
   Requestor never queries the worklist; RAD-80 §4.80.4.1.2.1 asks sites to configure the codes.
   So: per-node catalog only.
3. Transaction UID. Good catch. Editions up to 2025c write ?{transaction-uid}, 2026a writes
   ?{TransactionUid}, none defines the key in a table. What is unambiguous is PS3.4 CC.2.6.2: the
   Transaction UID travels in the N-SET data set (required IN PROGRESS, forbidden SCHEDULED), and
   dcm4chee-arc reads it only there. The client now sends it in the payload and as TransactionUid.
   2026a also added an optional ?requester={aetitle} to Change State and Request Cancellation;
   dcm4chee-arc wants a path segment instead, so the client takes a requester AE title plus a
   dcm4chee dialect flag. Both are on master (see link below) with a UpsWorkitem builder for the Task
   Requestor minimum (code, inputs per series with retrieval location, readiness READY, priority,
   Study UID, Referenced Request Sequence, patient with issuer).
4. Correction on my side. Weasis is the AIW-I Task Requestor (Create, RAD-80) grouped with a
   Watcher (Subscribe RAD-86, Open Event Channel RAD-109, Get Workitem RAD-83). Assigning the
   performer is the Task Manager's job, so forget my "re-address with Update Workitem": "Run" is
   Create when no non-terminal workitem with that code exists for the study, otherwise nothing.
   Progress comes from the subscription and the event channel, polling is the fallback; Request
   Cancellation stays for a queued task. See nroduit/weasis-dicom-tools@406b687

If there are other issues, you can create a PR.