XNAT Custom DICOM Routing Rules in the Admin UI

This feature uses the configuration for dicom/projectRules, which has now been moved to the top priority in project routing in XNAT 1.8 and exposed in the Admin UI. See How XNAT Scans DICOM to Map to Project/Subject/Session

In XNAT 1.7.6 and earlier, site admins can modify this setting via the legacy XNAT Site Configuration API. See: How to Set Custom DICOM Routing Rules via the XNAT API

When sending data to XNAT from a PACS terminal, there are often very few editable fields available to the user to tell XNAT where to route the data to and what to call it. This feature allows an XNAT site to customize exactly which field to examine, and what data entry pattern to look for.

Custom rules for identification of projects, subjects, and/or experiment labels may be defined in the XNAT Admin UI, under the tab named "Custom DICOM Routing." Each line of each configuration setting contains one rule, and the first rule matching the received file will be applied, ignoring any later matching rules.

Writing Custom Routing Rules

Editing these routing rules can lead to weird or unpredictable placement and labeling of sessions, depending on the structure of your incoming data. Make sure your users are aware of the rules you configure to prevent confusion.

The format for each rule definition is: (gggg,eeee):pattern:capturing-group-index

where (gggg,eeee) defines a DICOM tag to inspect, pattern is a regular expression in the same format used by java.util.regex.Pattern, and capturing-group-index (optional, defaults to 1) is the index of the group to use. 

Specifying a Single Rule in a DICOM Tag

Let's say that the PACS terminal user wants to type the XNAT project name into the DICOM field for Study Description (0008,1030) as follows:

Field entry for (0008,1030)

Project: ProjectA

The rule here is pretty simple. Look for the term "Project:", then look for whitespace, then look for one or more "word" characters (i.e., letters, digits, and/or the underscore character). The resulting custom DICOM routing rule and its RegEx pattern would look like this:

DICOM Routing Rule

(0008,1030):Project:\s*(\w+)

The XNAT Administrator would go to the Project Routing panel in the Site Administration UI, enable site-wide custom project routing, enter that rule in the code editor, and save the new configuration in their XNAT.

Specifying a Set of Rules in a DICOM Tag

Let's say that the PACS terminal user wants to specify the XNAT project, subject, and experiment label all in the same DICOM field – for example, in Patient Comments (0010,4000) – as follows:

Field entry for (0010,4000)

Project:ProjectA Subject:Subject001 Session:Subject001_MR1

In this case, you can use the capturing-group-index to identify which match corresponds to project/subject/session as follows:

Custom Project Routing Rule

(0010,4000):Project:(\w+)\s*Subject:(\w+)\s*Session:(\w+):1

Custom Subject Routing Rule

(0010,4000):Project:(\w+)\s*Subject:(\w+)\s*Session:(\w+):2

Custom Session Routing Rule

(0010,4000):Project:(\w+)\s*Subject:(\w+)\s*Session:(\w+):3

The XNAT Administrator would enter each of these into the appropriate panel in the Site Administration UI, enable site-wide custom routing rules for each, and save the new configurations in their XNAT.

Parsing Complex DICOM Tag Values

Let's say that the PACS terminal user has a process of adding the DICOM AE Title of your XNAT (in this case, "XNAT") to the project name. Or any other such complication. The resulting entry in the DICOM field might look like this:

Field entry for (0008,1030)

XNAT^ProjectA-1001_JUNK

This gives us a more complex problem to solve. At this point, we recommend using a Java Regex Tester to play with your RegEx structure, until you come out with a working pattern to filter with. You may end up with something like this:

DICOM Routing Rule

(0008,1030):(?:[^\^]+)\^((?:[a-zA-Z\d]+)[_\-](?:\d+))(.*?)

Once again, to implement this rule, the XNAT Administrator would go to the Project Routing panel in the Site Administration UI, enable site-wide custom project routing, enter that rule in the code editor, and save the new configuration in their XNAT. 

Performing String Replacement during Routing

Custom routing rules also offer simple regular expression replacement, which can be helpful in fixing improperly entered labels, For example, if your project name is "Project_A" but is consistently mislabeled as "Project-A", the site admin can define two additional parameters for "target regex" and  "replacement string" as follows: (gggg,eeee):pattern:capturing-group-index t:targetRegex r:replacementString

So, for example, if your Study Description tag contained XNAT^Project-A and you wanted to map this to project Project_A, you could use:

DICOM Routing Rule with String Replacement

(0008,1030):XNAT\^(.*):1 t:- r:_

Resetting the DICOM Project Routing Priority to Legacy versions of XNAT

For site admins of older versions of XNAT who were previously using the projectRules config, they may be surprised to find that it is now the first rule applied for project routing, as opposed to the fifth. See How XNAT Scans DICOM to Map to Project/Subject/Session.

This is only a breaking change if you were previously using the projectRules config and wanted it to be fifth in priority. To restore the old functionality, you can write a new set of custom DICOM project routing rules that places the legacy settings first in priority.

DICOM Project Routing Rule

(0010,4000):Project:([^\s]+).*
(0032,4000):Project:([^\s]+).*
(0008,1030):(.*)
(0008,0050):(.*)
// your custom rule here, as fifth pass

The XNAT Administrator would go to the Project Routing panel in the Site Administration UI, enable site-wide custom project routing, enter this set of rules in the code editor – each one on its own line – and save the new configuration in their XNAT.