XNAT Gateway Server User Manual

Troubleshooting: frequently asked questions

1 Introduction

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 Features

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:

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

5. The Main Screen

Once the server is configured this will be the first screen you see:

Status Screen

1. 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.
2. Shows how long the server has been running. This is reset everytime the server is (re)started.
3. Stops and starts the server.
4. Shows the server logs.
5. Allows you to configure XNAT servers. Explained in Configuring XNAT Servers.
6. 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

1. 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.
2. 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.
3. A unique name that refers to the default XNAT server. For example if the XNAT server is "https://cnda.wustl.edu/", "CNDA" would work well.
4. The actual hostname or IP address of the XNAT server. The CNDA, for example, is located at "https://cnda.wustl.edu/".
5. Your username for this XNAT server.
6. Your password for this XNAT server.
7. Keep these settings and start the server.
8. 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

1. A listing of the current XNAT servers that this XNAT Gateway knows about.
2. Add a new XNAT servers. Explained in the next step.
3. Deletes the highlighted XNAT server.
4. Edits the highlighed XNAT server. Explained in Step 7.2.
5. Makes the highlighed XNAT server the default server. All queries and retrievals will now go through this XNAT server.
6. Indicates the default XNAT server.

7.1 Adding an XNAT Server

Adding an XNAT Server

1. A unique name for the new XNAT server. Must be one word.
2. The hostname or IP of the new XNAT server.
3. Your username for the new XNAT Server.
4. Your password for the new XNAT Server.

7.2 Editing an XNAT Server

Editing an XNAT Servers

1. The hostname of this XNAT server.
2. Your username for this XNAT Server.
3. Your password for this XNAT Server.

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

1. The current AE title of this XNAT Gateway Server
2. The port on which this XNAT Gateway Server is listening for incoming requests.
3. Allows you to configure the XNAT Gateway Server's AE title and listening port. Explained in the next step.
4. A list of DICOM devices that are able to retrieve images using the XNAT Gateway Server.
5. Add a DICOM device to the list. Explained in step 8.2.1.
6. Delete a highlighted DICOM device from the list.
7. Edit the values of the highlighted remote DICOM device. Explained in step 8.2.2.

8.1 Configuring the XNAT Gateway

Change this XNAT Gateway's settings from this screen:

Gateway Settings Screen

1. Edit the current AE Title of this XNAT Gateway Server. This must be one word with no spaces.
2. Edit the listening port of this XNAT Gateway Server.

8.2 Configuring Remote DICOM Devices

8.2.1 Adding a Remote DICOM Device

The following screen allows you to add a new remote device:

Add Remote AE Screen

1. A unique name for this remote DICOM device. For example if you are using Osirix from a reading station to view images a good name would be "OSIRIX_READING". This must be one word with no spaces.
2. The AE title of your DICOM image viewing software. Please refer to your DICOM software manual to get this information. This must be one word with no spaces.
3. The hostname or IP address of the PC on which the DICOM image viewing software is installed.
4. The DICOM port on which your DICOM image viewing software is listening for connections. Please refer to your DICOM software manual to get this information.

8.2.2 Editing a Remote DICOM Device

The following screen allows you to edit an existing remote device:

Edit Remote AE Screen

1. 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.
2. The hostname or IP address of the PC on which the DICOM image viewing software is installed.
3. The DICOM port on which your DICOM image viewing software is listening for connections.

9. Advanced

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

1. After stopping the application open the properties file in a text editor.
2. Determine a unique name for the XNAT Server, eg. CNDA
3. Add the server name to the end of the "XNATServers" property. For example, if the XNATServers property is currently "XNATServers=MYXNATSERVER MYOTHERXNATSERVER", append CNDA to the end of that line so it reads "XNATServers=MYXNATSERVER MYOTHERXNATSERVER CNDA".
4. Add a hostname for this XNAT server to "XNATServers.<NAME>.ServerURL". For the CNDA example, add "XNATServers.CNDA.ServerURL=https://cnda.wustl.edu/"
5. Add a username for this XNAT server to "XNATServers.<NAME>.User". For the CNDA example, add "XNATServers.CNDA.User=your_username
6. Add a password for this XNAT server to "XNATServers.<NAME>.Pass". For the CNDA example, add "XNATServers.CNDA.Pass=your_password
7. If you want this to be the default XNAT server, locate the "XNATServers.default" property and set its value to this servers name. For the CNDA example, set "XNATServers.default=CNDA"
8. Save the file and restart the application

9.1.3 Adding a Remote DICOM Device Manually

1. After stopping the application open the properties file in a text editor.
2. Determine a unique name for the device, eg. OSIRIX
3. 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"
4. Add this device's AE title to Dicom.RemoteAEs.<NAME>.CalledAETitle. For the OSIRIX example, add "Dicom.RemoteAEs.OSIRIX.CalledAETitle=DEVICE_AE_TITLE"
5. Add this device's hostname to Dicom.RemoteAEs.<NAME>.HostNameOrIPAddress. For the OSIRIX example, add "Dicom.RemoteAEs.OSIRIX.HostNameOrIPAddress=your_hostname".
6. Add this device's listening port to Dicom.RemoteAEs.<NAME>.Port. For the OSIRIX example, add "Dicom.RemoteAEs.OSIRIX.Port=listening_port".
7. 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:

1. in the properties file, set
   Dicom.QueryDebugLevel=1
2. restart the server,
3. check the server log for DICOM exchange messages, and gateway.log file for XNAT-specific error messages.

9.2 XNAT Gateway Server Settings

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.