Basic DICOM object identification

When a file is received by the C-STORE SCP, the server attempts to identify a project into which the file should be placed and to derive subject and session identifiers. This page details XNAT's attempt to determine the project, subject, and session.

First pass: Patient Comments

XNAT first looks for all relevant metadata in the Patient Comments attribute (0010,4000). On many scanners, this is a freeform field that technicians can populate at the console. On Siemens' Syngo system, for example, this attribute holds the contents of the "Additional Information" box below the patient information section (which contains name, date of birth, etc.)

The identifiers should be entered as follows:Project: {Project_ID}; Subject: {Subject_ID}; Session: {Session_ID}

The assignments should be separated by semicolons (as above), by commas, or by whitespace. All other content is ignored. The label should contain only letters, digits, and the underscore character. Project_ID should be the abbreviated name for an existing project.

Second pass: Study Comments

The second pass applies all the rules from pass 1 above to the Study Comments attribute (0032,4000). This is a another freeform field; on the Siemens Syngo console, it is labeled "Study comments."

Third pass: Custom identification rules

Custom rules for project identification may be defined in the configuration file projects/{project name}/src/conf/dicom-project.rules. Each line of this file contains one rule, and the first rule matching the received file will be applied, ignoring any later matching rules. Note that if any changes are made to the rules file, the webapp must be redeployed and the Tomcat server restarted.

Adding or editing the dicom-project.rules file can lead to weird or unpredictable labeling of sessions. Make sure your users are aware of the rules you configure in this file to prevent confusion.

The format for each rule definition is: (gggg,eeee):pattern

where gggg and eeee are the four-hex-digit group and element indices, respectively, of the DICOM attribute to be examined for project information; and pattern is a regular expression, in the same format used by java.util.regex.Pattern. The pattern should contain at least one capturing group, which will be used to extract the prospective project name. If the pattern contains exactly one capturing group, or if the project name is expected to be found in the first capturing group of the pattern, then the format above will suffice. Otherwise, the alternate format (gggg,eeee):pattern:capturing-group-index should be used.

For example, the specification: (0008,1030):Project:s*(\w+) creates a rule that looks at the content of the DICOM attribute Study Description (0008,1030). If the value of that attribute equals the text "Project:" optionally followed by zero or more whitespace characters, then one more more "word" characters (i.e., letters, digits, and/or the underscore character), then the rule pattern matches the attribute value and will be used to attempt to try to determine the project to which the data belongs. The parenthesis around the \w+ pattern define a capturing group, and the text matching that portion of the attribute value will be used as a prospective project abbreviation. If XNAT contains the projects ProjectA, ProjectB, and ProjectC; the DICOM C-STORE SCP is configured with the above rule; and none of the files received contain project information in Patient Comments or Study Comments; then the following values for Study Description lead to these results:

Study Description value

Matches rule?

Capturing group content

Assigned project

No Project: here




Project: Project^A




Project: foo



undefined (no project named foo)

Project: ProjectA




Fourth pass: Study Description

Next, XNAT looks for each identifier by using the content of individual DICOM fields:


Attribute name

XNAT field


Study Description

Project ID


Patient Name

Subject ID


Patient ID

Session ID

Fifth pass: Accession Number

If no valid project label has yet been found, XNAT makes one last attempt to identify the project, using the content of Accession Number (0008,0050).

If, after all of the steps above, no match is found for an identifier, that identifier is left unfilled in the generated session XML document. Significantly, if no project could be identified, the session will be placed in the Unidentified prearchive, which can be viewed and modified only by administrator accounts. If the project is assigned, the session will be placed in the appropriate project prearchive.

If the subject label derived from the DICOM metadata does not match the label for an existing subject in the project, then subject information will need to be added manually in the XNAT web application.