Using DICOM Inbox to import an image session

Introduced in XNAT 1.7.6, DICOM Inbox is a way to import a DICOM image session that is already on the XNAT filesystem. This can be useful when you have a large amount of DICOM data on site that needs turned into XNAT image sessions by alleviating TCP traffic that would otherwise have to funnel through tomcat's network layer.

Workflow

Your application places an image session in a folder (SESSION) that can be accessed by the XNAT server. Imaging sessions must be in a directory with a name matching exactly the project ID of a project to which the user has write access, and this directory itself must be a subdirectory of the main inbox path configured in XNAT. Additionally, more than one session can be imported at once, but renaming is only supported for single session imports.
1. Local or network mounts are both supported.
2. The DICOM Inbox software requires all of the data for the image session to exist in the SESSION folder. Subfolders below SESSION are allowed.
Your application makes a REST call which includes
1. Absolute path to the folder to be imported (SESSION).
2. Project that will be the home of the image session.
3. User credentials.
4. New session name (Optional).
When it services the REST call, the XNAT system places the request on a queue. The request will be handled asynchronously; your client application will not receive notification of completion (success or error).
1. The XNAT system will copy or move the image data into XNAT. Depending on the project's settings, the image session data will either be sent to the prearchive where it remains there until additional action is taken, or it moves transiently through the pre-archive into the archive without additional user input.
2. There is a parameter to delete original copies of the data after import.
The XNAT system does not provide a web user interface that is tailored to allow you and/or an administrator to check import progress. The user can monitor progress/status by examining the pre-archive or archive using the standard XNAT user interface. Some issues in the import will not be caught when the import call is returned. These issues will result in a 200 (OK) HTTP response, but the data never makes it to the pre-archive. Because there is no UI to view the status of requests, you will need to make REST calls to retrieve the status of such requests.

Anonymization and Archiving

Image sessions imported via DICOM Inbox are archived via the Gradual DICOM Importer and are anonymized in the same way as any image sessions uploaded via the Compressed Uploader.

Usage Example

You can import using DICOM inbox via REST like so:

CODE

curl -u admin -X POST "http://localhost:8080/data/services/import?import-handler=inbox&cleanupAfterImport=false&PROJECT_ID=test_proj&SUBJECT_ID=test_subj&EXPT_LABEL=test_exp&path=/data/xnat/inbox/a_proj/b/c" -k

Parameters

Parameter	Value	Required	Description
import-handler	inbox	Y	Specifies the DICOM-Inbox importer
cleanupAfterImport	true false (default)	N	Set to true if you want the files to be deleted from the source location after they are moved into XNAT
PROJECT_ID	Project ID	Y	Requires a valid XNAT Project ID that your user has write access to as the archive destination
SUBJECT_ID	Subject ID	N	Requires a valid XNAT Subject ID within the specified project as the archive destination
EXPT_LABEL / session	Session Label	N	Optional label assignment to give the image session, once imported
path	/data/xnat/inbox/{path}	Y	the absolute path to the files you want to import. The path must be within a subdirectory of the inbox directory that matches the ID of a project you have edit access to and the destination project must be one you have edit access to.

Results

After you issue a request, a URL will be returned that you can use to check the status of your request. You can also check on the status of requests using the DICOM Inbox Transaction API.