Image Session Import Service API
Contents
Upload An Image Session
Introduced with XNAT 1.5, the import service is a customizable upload implementation for importing data into XNAT. XNAT comes with several pre-configured import implementations, but can be configured via java to meet any need.
The import is built to receive a zip, tar.gz, etc and place it into the prearchive or archive space. It has also been modified to import files from the user's cache space, which would have been previously uploaded.
POST - /data/services/import
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 "SI".
Option | Description |
---|---|
SI | standard session importer: Used to import individual DICOM or ECAT files or zips of DICOM or ECAT files. |
gradual-DICOM | same implementation as XNAT's integrated DICOM receiver Accepts individual DICOM files and follows the DICOM receiver mapping/archive logic |
DICOM-zip | similar to the gradual-DICOM 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. (NOTE: if your zip includes an erroneous file (e.g., non DICOM or invalid DICOM), DICOM-zip will return a 400 error, but any files uploaded prior to the erroneous one will still wind up in 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 | uses its own workflow, as documented here: Using DICOM Inbox to import an image session |
All Parameters
All parameters are optional, though the 'dest' is highly encouraged
Parameter name | Parameter description | Supporting import handlers |
---|---|---|
overwrite |
| SI |
overwrite_files |
| SI |
quarantine |
| SI, inbox |
triggerPipelines |
| 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:
| 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).
| SI, gradual-DICOM (archive destinations unsupported), DICOM-zip (archive destinations unsupported) |
import-handler | Defaults to standard import logic ("SI"). 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
| 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
| -- |
rename | Used with the gradual-DICOM importer, instructing XNAT to ignore the original dicom file name and rename it. Default is false.
| 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 | SI, inbox, DICOM-zip, gradual-DICOM |
SUBJECT_ID | For use when not using dest attribute | SI, inbox, DICOM-zip, gradual-DICOM |
EXPT_LABEL | For use when not using dest attribute | SI, inbox, DICOM-zip, gradual-DICOM |
session | Alternative property for EXPT_LABEL supported by some import handlers | SI, inbox |
Ignore-Unparsable | XNAT 1.8.3+ only
| DICOM-zip |
Direct-Archive | XNAT 1.8.3+ only
| DICOM-zip, gradual-DICOM |
Refresh The Archive Catalog XML
Introduced with XNAT 1.6.2, 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 the, 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