mwlkit

Turn an HL7 v2 imaging order into a DICOM Modality Worklist item, with every mapping choice sourced and every invented value reported.

Built on hl7kit for the message and dicom-object for the data set. Compiles for wasm32-unknown-unknown; the dicomscope demo builds the item in the browser and lets you download it.

What a worklist item is

Before an examination the modality asks the Modality Worklist SCP, with a C-FIND, what is scheduled for it. Each answer is one data set in the Modality Worklist Information Model (DICOM PS3.4 Annex K, Table K.6-1): patient identification, the imaging service request (order numbers, accession number), the requested procedure (procedure ID, Study Instance UID) and one or more Scheduled Procedure Steps (modality, station, start time). The modality copies Patient ID, Accession Number, Study Instance UID, Requested Procedure ID and SPS ID verbatim into every image it produces. That data set is the hinge of RIS/PACS linkage: what goes wrong here is what the archive and the reporting system fight over later.

The mapping follows IHE Radiology Technical Framework Volume 2, transaction RAD-4 "Procedure Scheduled", with dcm4che's HL7-to-MWL behaviour noted where it differs. Every line in src/map.rs says which document it comes from, or says unsourced and why.

use hl7kit::{order::Order, Message};
use mwlkit::{to_bytes, worklist_item, Input, Options};

let msg = Message::parse(text)?;
let order = Order::extract(&msg);
let item = worklist_item(&Input { message: &msg, order: &order }, &Options::default())?;
for w in &item.warnings {
    eprintln!("{w}");
}
std::fs::write("order.mwl.dcm", to_bytes(&item)?)?;

The mapping

Types are those of Table K.6-1. Sources: IHE RAD-4 unless marked.

Not mapped in this version: Institution Name (MSH-4 is a facility code, not a name), Patient's Weight, Medical Alerts and Allergies, NTE comments.

Person names

HL7 XPN is family^given^middle^suffix^prefix; DICOM PN is family^given^middle^prefix^suffix. The two outer components swap. XCN (ORC-12, OBR-16, PV1-8) has the person ID in front and is handled too. When a prefix or suffix is present the reorder is reported as Warning::NameComponentsReordered, because a reviewer comparing the two sides will otherwise see a difference that is not an error.

Study Instance UID policy

The only value this crate ever invents. When IPC-3, ZDS-1 and the DCM 110180 OBX are all absent, Options::uid_policy decides:

• Dcm4cheStyle (default): a deterministic name-based UID from the Requested Procedure ID, else from the Accession Number, else an error. This mirrors dcm4che, which derives a name-based UID from those identifiers so the same order always yields the same UID. It is dcm4che-style, not dcm4che-identical: dcm4che uses UUID version 5, this crate a version 8 hash, both under the 2.25. UUID-derived root of PS3.5 B.2, which needs no registered root and fits the UI limit.
• Random(u128): the caller's random bits as a 2.25. UID. The crate has no random source and does not pretend to.
• Refuse: fail with MwlError::NoStudyUid.

A generated UID is always reported as Warning::StudyUidGenerated and WorklistItem::study_uid.origin says Generated. The consequence is visible in the demo's chain view: the modality copies this UID into the images, and the RIS never learns it.

Length policy

DICOM VR limits: SH 16, LO 64, PN 64, AE 16, CS 16, UI 64 characters. Real RIS accession numbers are often longer than 16. Options::length_policy:

• Refuse (default): MwlError::TooLong naming the attribute. A cut accession number is a different key from the one the RIS holds.
• TruncateAndWarn: cut and report Warning::Truncated, to see what a lenient interface would have produced.

AE and UI are never truncated under either policy: a cut AE title is a wrong destination and a cut UID is a different study.

Writing to a file

A worklist item is a C-FIND response, not a stored object, so the standard defines no file format for it. to_bytes writes a Part 10 file anyway, because that is what file-based worklist SCPs (dcm4che wlmscpfs, Orthanc's worklist plugin) read: Media Storage SOP Class 1.2.840.10008.5.1.4.31 (Modality Worklist Information Model - FIND), a deterministic 2.25. instance UID, Explicit VR Little Endian.

Non-goals

No MLLP, no C-FIND, no network code of any kind. No guessing: a modality is never inferred from procedure text, a coding scheme is never invented, a Type 1 attribute is refused rather than filled with a placeholder.

License

MIT OR Apache-2.0, like the rest of the workspace.