Troubleshooting: frequently asked questions
Quick Index
The XNAT Gateway server allows to query and retrieve DICOM images from XNAT servers using any DICOM client, such as DICOM viewer (OSIRIX, K-PACS, ...), MR scanner software, or PACS archive. You can install the Gateway locally and connect to it as to any other DICOM server. DICOM requests are translated into XNAT requests, and the result is returned over DICOM networking protocol.
You can browse the XNAT archive at Study (Experiment in XNAT) level and Series (Scan in XNAT) levels.
Use the following DICOM fields to query XNAT from your DICOM software:
DICOM search field | XNAT field |
---|---|
Patient name | Subject label |
Patient ID | Subject ID |
Accession number | Experiment label |
Modality | Image session type |
Using Gateway, you can retrieve an entire study or an individual series. Image-level retrieve is not supported.
NOTE. Currently, Gateway supports C-MOVE only (this is default in most DICOM software).
Please refer to the installation page to download the correct package for your platform.
Directory | Description |
---|---|
src | (application source code) |
config | (configuration files) |
dist | (distributed application JAR) |
doc | (location of this manual) |
build | (class files generated during compilation) |
lib | (external libraries needed by this application) |
nbproject | (configuration files for the Netbeans IDE) |
Once the server is configured this will be the first screen you see:
Status Screen
The first time the XNAT Gateway GUI is run, you will see the initial setup screen.
Initial Setup Screen
This form must be filled out completely in order to start the server.
You can now define multiple XNAT servers from which to query and retrieve images although only one is active at any given time. The following screen shows an overview of the current XNAT servers listed and the ability toggle a default server, and add and edit new servers:
Configure XNAT Servers Screen
Adding an XNAT Server
Editing an XNAT Servers
The Local/Remote AE Configuration screen shows the current setting for this XNAT Gateway and the devices that are able to retrieve images.
Local/Remote AE Configuration Screen
Change this XNAT Gateway's settings from this screen:
Gateway Settings Screen
The following screen allows you to add a new remote device:
Add Remote AE Screen
The following screen allows you to edit an existing remote device:
Edit Remote AE Screen
All the configurable options of the XNAT Gateway Server are stored in "./<XNAT_SERVER_INSTALL_DIR>/config/gateway.properties" where XNAT_SERVER_INSTALL_DIR is the root directory containing the XNAT Gateway Server source code and documentation.
This properties file contains a number of settings some of which can be changed in the GUI. Please do not edit this file while the application is running.
This file is read on application startup and written as you make changes to the application settings (eg. if you add a new XNAT database). If there is an error in the properties file that setting is ignored, and a backup properties file is created. If a change you made is not appearing in the GUI this is the first place to look.
In case of error in reading the properties file, it is backed up to "gateway.properties.bak" in the application root directory.
If you encounter retrieve error when the DICOM images from XNAT server are not displayed in the workstation:
Setting | GUI Configurable | Description |
---|---|---|
Dicom.CalledAETitle | Yes | The AE title of this XNAT Gateway Server. |
Dicom.ListeningPort | Yes | The port on which this XNAT Gateway Server listens for incoming requests from DICOM devices. |
Logger.Output | No | Configures where errors are sent. The default setting is "file" - if it is changed no logging will occur. The log file is hard-coded to "gateway.log" in the application's root directory.. |
Dicom.DebugLevel | No | Control the verbosity of log messages. This defaults to 1 which just logs warning messages. Anything above 2 logs a huge amount of data (on the order of thousands of messages per transaction) so please use values above 2 only for debugging purposes. |
Application.SavedImagesFolderName | No | The location where images retrieved from the XNAT databases are stored. Every time the server is (re)started, these images are deleted. By default the location is set to the temporary directory of your operating system. |
XNATServers | Yes | A list of XNAT databases |
XNATServers.default | Yes | The default XNAT database. |
XNATServers.<NAME>.ServerURL | Yes | The hostname of the <NAME> XNAT database |
XNATServers.<NAME>.User | Yes | The username of the XNAT database |
XNATServers.<NAME>.Pass | Yes | The password of the XNAT database |
Dicom.RemoteAEs | Yes | The list of DICOM devices that can retrieve images via this server |
Dicom.RemoteAEs.<NAME>.CalledAETitle | Yes | The AE title of the <NAME> DICOM device |
Dicom.RemoteAEs.<NAME>.HostNameOrIPAddress | Yes | The hostname of the <NAME> DICOM device |
Dicom.RemoteAEs.<NAME>.Port | Yes | The port on which the <NAME> DICOM device listens for DICOM data. |
Q1: When I try to start the XNAT Gateway in Linux, I get the message: "Server startup error! Permission denied (Bind failed)."
A1: This is most likely due to Linux security policy. Go to AE configuration->change/configure->Gateway Settings->change. Use server port number > 1024.
Q2: Any DICOM query to XNAT Gateway fails.
A2: Starting with October 2017 version, DICOM Query is by default restricted to specified DICOM Application Entities (AEs). Use AE configuration->Chage/Configure->Remote Devices to configure all DICOM clients that will be quering the Gateway.
To allow query from any AE, edit the config/qrscp-config.xml, and change the line
<attribute name="UnrestrictedQueryPermissionsToAETitles" type="java.lang.String">NONE</attribute>
to the line:
<attribute name="UnrestrictedQueryPermissionsToAETitles" type="java.lang.String">ANY</attribute>
Q3: DICOM query to XNAT Gateway works, but I can't download DICOM studies.
A3.1: Make sure that the condition in A2 is satisfied.
A3.2: Make sure that the DICOM data hosted by XNAT server has DICOM-conformant UID tags populated (StudyInstanceUID, SeriesInstanceUID, Patient ID).
A3.3: If C-GET doesn't work, try C-MOVE (configure your DICOM software to use C-MOVE to retrieve images)
A3.4: There may be an issue with your local XNAT server's CA SSL certificate. Gateway may not work properly with some types of SSL certificate at target XNAT server. Test your Gateway+DICOM client setup against a public XNAT server such as central.xnat.org.
Q4: I need to change the way XNAT fields are mapped to DICOM fields by Gateway. Is there an easy way to do that?
A4: Refer to this discussion.