DICOM Instance File Naming and Uniqueness

Use extreme caution when changing dicomFileNameTemplate: it must be unique per instance or data will be overwritten silently.

Templatized DICOM File Naming 

XNAT has long had a configuration, dicomFileNameTemplate, to control how DICOM instance files are named. Specifically, this value controls the naming of DICOM files ingested via GradualDicomImporter (e.g., gradual-DICOM, DICOM-zip, C-STORE), unless rename = false. Variables must be dcm4che tag names, or to compute a hash of tags, prefix with "Hash" and join tag names using the word "With", for example: HashTag1WithTag2WithTag3. Variables should be demarcated with ${} per the StringSubstitutor class, for example: ${SOPInstanceUID}. Use extreme caution when changing this value: it must be unique per instance or data will be overwritten silently. Additionally, changing this value may lead to duplicated DICOM files on merge unless using SOP Instance UID to uniquely identify DICOM, more on this below. The dicomFileNameTemplate configuration defaults to ${StudyInstanceUID}-${SeriesNumber}-${InstanceNumber}-${HashSOPClassUIDWithSOPInstanceUID}, and will replace tags it cannot find with "no-value-for-<tag name>". 

You may change this configuration without restarting tomcat, and changes will take effect immediately. However, there is no way for XNAT to revert to the previously configured value if there are issues with the new one, so use caution with changes and check the XNAT logs after modification to ensure there aren't any issues. We also recommend conducting some test imports after changes.

DICOM Instance Uniqueness

Prior to 1.8.7, XNAT used file names to identify duplicate DICOM instances during merge operations. This can be problematic if the dicomFileNameTemplate configuration changes, or if some files are uploaded with rename=false while others are not. Accordingly, we have changed to using SOP Instance UID to uniquely identify DICOM instances, regardless of filename. Filenames must still be unique within a given scan, but if a DICOM instance comes in with a distinct name but a SOP Instance UID that matches an existing instance in the scan, XNAT will consider it an overwrite and behave accordingly.

If you prefer to retain the old behavior, we have added a configuration, useSopInstanceUidToUniquelyIdentifyDicom, which you may set to false to continue to use file name as the source of DICOM instance uniqueness. You would wish to do this if you know your scanner doesn't always assign a distinct SOP Instance UID (e.g., if you also need to consider SOP Class UID).

If you are going to change the dicomFileNameTemplate configuration, it is highly recommended that you set useSopInstanceUidToUniquelyIdentifyDicom=true.