Skip to end of metadata
Go to start of metadata

This documentation will be supplemented with additional API documentation in the XNAT API docs


New 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

  1. 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.
  2. 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).
  3. 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.
  4. 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:

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

You need to make sure you set the import-handler to inbox, cleanupAfterImport to true if you want the files to be deleted from the source location after they are moved into XNAT and false otherwise, PROJECT_ID and SUBJECT_ID to the project and subject you want it to be placed in, EXPT_LABEL to the label you want to be assigned to the session you're importing, and path to 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. 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 Swagger ( /xapi/swagger-ui.html#/dicom45transaction45api ).



1 Comment

  1. Questions:

    • Is there an API for discovering what folders / sessions exist in the Inbox, or is that handled strictly through direct access to the file system? In other words, could the contents of the Inbox be exposed in the UI?
    • What happens if you specify a path to a folder containing more than one session?
    • For bulk uploads, does a user have to write out an API call for each and every session in the inbox that they want to upload? Or is there an easier way to queue multiple sessions for import?
    • What kind of report is generated, if any, upon success or failure of the import?