This XNAT plugin extends the routing capabilities of XNAT, allowing more flexibility to route incoming sessions based on DICOM metadata.
The XNAT core routing system can read DICOM metadata and route sessions to Projects / Subjects / Sessions, based on the metadata found in certain DICOM tags.
Since XNAT 1.8, the core routing system has been improved by the Custom Routing rules, which allows administrators to map DICOM tags to project / subject / session fields using regular expressions.
To resume the routing process, the precedence of the routing rules is as follows in standard XNAT:
- Administrator defined routing rules: These are the custom routing rules defined by the administrator in the XNAT Admin UI.
- Composite fields: The project, subject and session can be extracted from a formatted string in the form:
Project:project Subject: subject Session:session
The composite field can be stored in the DICOM tag (0010,4000) (Patient Comments) or (0032,4000) (Study Comments).
- Single entries in DICOM tags: XNAT has further hard coded rules to extract exact single values from certain DICOM tags. See the XNAT documentation for more details.
This routing system is powerful but has the following limitations:
-
It does not allow to route sessions based on a combination of multiple DICOM tags (for example, if you want the session name to combine the date of the exam and the patient id).
-
Whereas it can create new subjects, it can't route sessions to projects which do not exist yet. A session which does not match any of the routing rules will stay "Unassigned" in the prearchive, without further action.
This plugin aims to overcome the preceding limitations. To allow more flexibility in routing sessions, it applies a DicomEdit script to the incoming DICOM files, which can modify the DICOM metadata before the routing process is applied.
More specifically, it will extract project, subject and session information from the DICOM metadata, using a DicomEdit script written by an administrator,
and write a composite field in one of the two DICOM tags XNAT tries to parse for it (either (0010,4000) or (0032,4000)).
This operation will be performed on all incoming sessions, before the project is determined by XNAT.
It will also handle the case where the project does not exist yet, by either creating it automatically (and route the new session to it), or by sending an email notification to the XNAT admin.
flowchart LR
A[Incoming<br>DICOM session] --> B[Apply DicomEdit script<br><br>Composite field<br>in 0010,4000 or 0032,4000]
B --> C{Project<br>exists?}
C -- Yes --> H["XNAT Custom Routing<br>(recommended<br>to disable it)"]
C -- No --> E{Auto<br>project<br>creation?}
E -- Yes --> F[Create new project]
E -- No --> H
F --> H
H --> I[Routing based on<br>Composite Field]
classDef plugin fill:#b5dead,stroke:#333,stroke-width:2px
classDef custom fill:#ff9966
class B,C,E,F plugin
class H custom
Installing the plugin is a two-step process:
- Get the plugin JAR file (either by downloading it from the releases or building it from source).
- Deploy it to your XNAT instance:
- Copy the JAR file to the
pluginsfolder of your XNAT instance. - Restart XNAT to load the new plugin.
- Copy the JAR file to the
From Github releases page: https://github.com/ParisBrainInstitute/DicomEdit-Routing/releases
Clone this repository and build the plugin using Gradle:
./gradlew clean buildMove the JAR file to the plugins folder of your XNAT instance, then restart the XNAT server.
mv dicom-edit-routing-<version>.jar /path/to/xnat/data/home/plugins/
sudo systemctl restart tomcatTo configure the plugin, navigate to Administer > Plugin settings > Dicom Edit Routing. There, you can set the following options:
- Enable DicomEdit Routing: Enable or disable the processing of incoming DICOM sessions by the plugin.
- DicomEdit Version: The version of the DicomEdit script to use. This should match the version of the DicomEdit script you have written.
- Project Routing Script: The part of the DicomEdit script that will be used to extract the project. It must assign a value to the project variable. The script must use DicomEdit syntax to access DICOM tags.
- Subject Routing Script: The part of the DicomEdit script that will be used to extract the subject.
- Session Routing Script: The part of the DicomEdit script that will be used to extract the session.
- Composite Field: The DICOM tag where the composite field will be written. This can be either
(0010,4000)(Patient Comments) or(0032,4000)(Study Comments). XNAT will try to read the composite field from this tag.
Here are some examples of DicomEdit scripts:
project := (0008,1030)
project := "Undefined"
regex := "(\\w+)[_\\s](.*)"
if (ismatch[(0008,1030), regex]) {
project := match[(0008,1030), regex, 2]
}
else {
project := (0008,1030)
}
subject := "Undefined"
isPresent[(0010,0010)] ? subject := (0010,0010)
isPresent[(0010,0020)] ? subject := (0010,0020)
studyDate := "00000000"
isPresent[(0008,0020)] ? studyDate := (0008,0020)
studyDate := format["{0}_{1}_{2}", substring[studyDate, 0, 4], substring[studyDate, 4, 6], substring[studyDate, 6, 8]]
session := format["{0}_{1}", studyDate, subject]
The global DicomEdit script will be computed and displayed in the UI. If a basic error (like a syntax error) is detected at this stage, it will display an error message (but it will not prevent the plugin from being enabled). Note that errors can also occur at runtime, when the DicomEdit script is applied to incoming sessions.
The "Unknown Projects Settings" sestion allows you to configure the behavior of the plugin when a project does not exist yet:
When the plugin is enabled, it will automatically route incoming sessions based on the DicomEdit script.
If a session is not routed as expected, you can check the dicom-edit-routing.log logs for errors related to the DicomEdit script.
It is recommended not o mix the DicomEdit routing with the XNAT custom routing rules, as it can lead to unexpected behavior.