Surveying and Mitigating XNAT DICOM Resources

XNAT's resource survey function was developed to find and rectify issues arising from changes in XNAT's default file naming scheme. This could result in files named incorrectly but, more importantly, files in the same scan with different names but representing the same DICOM instance. The implications of these issues include:

  • Possible disclosure of protected, sensitive, and confidential information, for example by including a subject or patient ID in a file name or by not overwriting an existing DICOM instance with a new version of the same instance that may have had a higher level of anonymization applied
  • Non-compliant DICOM leading to strange results, for example when a viewer or processing workflow tries to analyze data but finds replicated frames

Detecting and correcting these errors requires two steps:

  • Surveying consists of grouping all of the files in a particular DICOM resource by SOP class and instance UIDs, calculating the expected name of the file based on the DICOM metadata, and then identifying instances where:
    • The name of the DICOM instance file stored in the archive doesn't match the expected file name (this is a mismatch)
    • Two files with different names have the same SOP class and instance UID as one or more other files and so represent the same DICOM instance (these are duplicates)
  • Mitigating consists of taking the report generated by the survey and then:
    • Backs up all mismatched and duplicate files
    • Renames mismatched files to the expected name
    • Renames one of the files from each set of duplicates to the expected name (if it's not already named that) and removes the rest of the duplicates

Separating the survey and mitigation processes into two discrete steps provides the opportunity to run the survey operation, inspect the resulting survey reports before any file is moved, renamed, or deleted, and either proceed with the default mitigation process or use the survey report to mitigate issues manually so you'll know what files will be changed during mitigation.

Because this functionality touches critical data on the back-end, no files are actually deleted. Instead all mismatched or duplicated files are copied to a safe location in XNAT's cache folder before being restructured in the archive folder. The report generated during mitigation provides detailed information on which files were moved and where. See the section Queuing resource mitigation requests in the user guide for more information.

To prevent large sessions from causing performance issues, these tasks are done in the smallest increments possible at the resource level. However, you can create and queue resource survey requests at the project level. This is described in Creating and queuing resource survey requests.

This documentation consists of the following sections:


There is no REST API reference for this functionality. Instead you should open the Swagger page for your XNAT installation and find the section labeled resource-survey-api.

XNAT is an open source project produced by NRG at the Washington University School of Medicine | NRG Home

Contributions to the XNAT Documentation site are licensed under a Creative Commons Attribution 3.0 Unported License. Creative Commons License

$label.name