Image Session Import Service API

The import service is a customizable upload implementation for importing data into XNAT. XNAT comes with several pre-configured import implementations, but new ones can be configured via java to meet any need.

The import service is built to receive or locate DICOM image session files and place them into the prearchive or archive space.

Usage

CODE

POST - /data/services/import

(See below for querystring parameters)

Files

Files are attached in the body of the request. "inbody=true" must be set as a parameter.

Select An Import Handler

Using the import-handler parameter, you can specify a specific implementation of the import logic. If this parameter is not specified, the default is "DICOM-zip".

Option	Description
SI (Deprecated)	Legacy session importer: Used to import individual DICOM or ECAT files or zips of DICOM or ECAT files.
gradual-DICOM	This importer is used in XNAT's integrated DICOM SCP receiver. Accepts individual DICOM files and follows the DICOM receiver mapping/archive logic
DICOM-zip	Similar to the gradual-DICOM importer but accepts zipped collections of DICOM files. This is used by the XNAT Upload Assistant and XNAT Desktop Client. As of XNAT 1.8.3, .tar.gz and .tar archives are also supported. There is a parameter to ignore unparseable files. If your zip includes an unparseable file (e.g., non DICOM or invalid DICOM) and this flag is unset, DICOM-zip will return a 400 error, but any files uploaded prior to the erroneous one will still be sent to the prearchive, so you can wind up with a partial session if you have auto-archive enabled.
XAR	Used to upload XAR files (zip files which include the session xml and the associated files)
inbox	Parses files that have already been uploaded to the filesystem, as documented here: Using DICOM Inbox to import an image session

Querystring Parameters

All parameters are optional, though the 'dest' is highly encouraged. If no parameters are entered, image sessions are routed to projects based on their inherent metadata. See How XNAT Scans DICOM to Map to Project/Subject/Session

Parameter name	Parameter description	Supporting import handlers
overwrite	none (DEFAULT): Do not overwrite existing xml or files append: Add content to existing xml & file system, but do not overwrite existing files delete: Upload new data, and overwrite any existing files.	SI DICOM-zip
overwrite_files	true: allow files to be overwritten for merges false: do not allow files to be overwritten for merges	SI DICOM-zip
quarantine	false (DEFAULT): follow project settings for whether new/modified archive content should go into quarantine true: override project settings and place new/modified archive content in quarantine.	SI inbox
triggerPipelines	true (DEFAULT): run the AutoRun pipeline for any archived sessions which are modified/created by this import false: Do not run the AutoRun at this time	SI inbox
src	Only used when attempting to import a previously uploaded file. You can specify multiple src attributes or separate them with commas. Example: /user/cache/resources/X/files/X.zip	SI gradual-DICOM DICOM-zip XAR
dest	Specifies intended destination. If it is empty, it will review the uploaded content and attempt to put it in the right place (or leave it in the prearchive Unassigned). /prearchive It will try to determine the proper project from the DICOM/ECAT headers. /prearchive/projects/PROJECT /prearchive/projects/PROJECT/timestamp /prearchive/projects/PROJECT/timestamp/session Importing to this url would allow you to merge additional content with previously uploaded content. /archive It will try to determine the proper project from the DICOM/ECAT headers. /archive/projects/PROJECT /archive/projects/PROJECT/subjects/SUBJECT /archive/projects/PROJECT/subjects/SUBJECT/experiments/LABEL Importing to this url would allow you to merge content with previously archived data.	SI gradual-DICOM (archive destinations unsupported) DICOM-zip (archive destinations unsupported)
import-handler	Defaults to the DICOM-zip importer. Client can specify a key using free-form text which the server maps to a different implementation of the import logic. See above.	--
http-session-listener	Used by the web based zip uploader free-form text: which should uniquely identify this upload process. If this is used, an http-session variable will be created using this text as the attribute ID, and will contain process/status information.	SI XAR
inbody	Used to tell the server that the body of the message is the actual file. This shouldn't be necessary if all upload tools set the Content-Type header appropriately. But, many do not. If your upload is failing and you can't figure out why, try setting this to true true: the body of the message is the actual file	--
rename	Used with the gradual-DICOM importer, instructing XNAT to ignore the original dicom file name and rename it. Default is false. true: renames each DICOM file in this pattern: `${StudyInstanceUID}-${SeriesNumber}-${InstanceNumber}-${HashSOPClassUIDWithSOPInstanceUID}.dcm`	DICOM-zip gradual-DICOM inbox
PROJECT_ID	For use when not using dest attribute. If you're uploading ECAT data via SI and it's not working, try using project as the parameter name instead	All
SUBJECT_ID	For use when not using dest attribute	All
EXPT_LABEL	For use when not using dest attribute	All
project	Alternative property for PROJECT_ID supported by some import handlers	DICOM-zip
subject	Alternative property for SUBJECT_ID supported by some import handlers	DICOM-zip
session	Alternative property for EXPT_LABEL supported by some import handlers	DICOM-zip SI inbox
Ignore-Unparsable	XNAT 1.8.3+ only true: silently discard files within zip/tar archive which are not readable as DICOM files false (DEFAULT): reject upload when zip/tar archive contains non-DICOM files	DICOM-zip
Direct-Archive	XNAT 1.8.3+ only true: use direct-to-archive import behavior to bypass the prearchive: Using Direct-to-Archive Uploading false (DEFAULT): use standard upload mechanism	DICOM-zip gradual-DICOM

Refresh The Archive Catalog XML

The refresh catalog service is used to update catalog xmls that are out of sync with the file system. This service can be used to store checksums for entries that are missing them, remove entries that no longer have valid files, or add new entries for files that have been manually added to the archive directory.

See: Catalog Refresh API