Troubleshooting: frequently asked questions
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.
2.1 Querying for DICOM studies
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|
2.2. Loading DICOM images
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).
3. Installing and running
Please refer to the installation page to download the correct package for your platform.
4. Application folders
|src||(application source code)|
|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)|
5. The Main Screen
Once the server is configured this will be the first screen you see:
- Shows whether the server is running or not. "Running" indicates the server is listening for incoming requests from other DICOM devices such as Osirix. "Stopped" indicates that the server is not listening and incoming requests will fail.
- Shows how long the server has been running. This is reset everytime the server is (re)started.
- Stops and starts the server.
- Shows the server logs.
- Allows you to configure XNAT servers. Explained in Configuring XNAT Servers.
- Allows you to configure dicom devices including this XNAT Gateway and remote DICOM devices.
6. Initial Configuration
The first time the XNAT Gateway GUI is run, you will see the initial setup screen.
Initial Setup Screen
- Since the XNAT Gateway Server emulates a DICOM device it must have an AE (Application Entity) title. This is the DICOM name by which your image viewing software will refer to the server. Any unique name, such as "XNATGATEWAY" will do.
- The server also requires a port number on which to listen for incoming requests. Any port number that is not currently in use will do, typically for DICOM devices 4006 and 4008 will work.
- A unique name that refers to the default XNAT server. For example if the XNAT server is " ", "CNDA" would work well.
- The actual hostname or IP address of the XNAT server. The CNDA, for example, is located at " ".
- Your username for this XNAT server.
- Your password for this XNAT server.
- Keep these settings and start the server.
- Exit the application.
This form must be filled out completely in order to start the server.
7. Configuring XNAT Servers
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
7.1 Adding an XNAT Server
Adding an XNAT Server
7.2 Editing an XNAT Server
Editing an XNAT Servers
8. Configuring DICOM Devices
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
8.1 Configuring the XNAT Gateway
Change this XNAT Gateway's settings from this screen:
Gateway Settings Screen
8.2.1 Adding a Remote DICOM Device
The following screen allows you to add a new remote device:
Add Remote AE Screen
8.2.2 Editing a Remote DICOM Device
The following screen allows you to edit an existing remote device:
Edit Remote AE Screen
- The AE title of your DICOM image viewing software. Please refer to your DICOM software to get this information. This must be one word with no spaces.
- The hostname or IP address of the PC on which the DICOM image viewing software is installed.
- The DICOM port on which your DICOM image viewing software is listening for connections.
9.1 The Properties File
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.
9.1.1 Accessing the Properties Backup File
In case of error in reading the properties file, it is backed up to "gateway.properties.bak" in the application root directory.
9.1.2 Adding An XNAT Server Manually
- After stopping the application open the properties file in a text editor.
- Determine a unique name for the device, eg. OSIRIX
- Add the device name to end of "Dicom.RemoteAEs". For the OSIRIX example, if the Dicom.RemoteAEs property is currently "Dicom.RemoteAEs=MYDEVICE MYOTHERDEVICE", append OSIRIX to the end of that line so it reads "Dicom.RemoteAEs=MYDEVICE MYOTHERDEVICE OSIRIX"
- Add this device's AE title to Dicom.RemoteAEs.<NAME>.CalledAETitle. For the OSIRIX example, add "Dicom.RemoteAEs.OSIRIX.CalledAETitle=DEVICE_AE_TITLE"
- Add this device's hostname to Dicom.RemoteAEs.<NAME>.HostNameOrIPAddress. For the OSIRIX example, add "Dicom.RemoteAEs.OSIRIX.HostNameOrIPAddress=your_hostname".
- Add this device's listening port to Dicom.RemoteAEs.<NAME>.Port. For the OSIRIX example, add "Dicom.RemoteAEs.OSIRIX.Port=listening_port".
- Save the file and restart the application.
9.1.4 Error Tracking
If you encounter retrieve error when the DICOM images from XNAT server are not displayed in the workstation:
- in the properties file, set
- restart the server,
- check the server log for DICOM exchange messages, and gateway.log file for XNAT-specific error messages.
9.2 XNAT Gateway Server Settings
|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.|
10 Frequently asked questions & troubleshooting
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.